<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Make Controller Kit - Firmware API: rtos.c Source File</title>
<link href="mt_doxygen.css" rel="stylesheet" type="text/css" />
<link href="../resources/mt_doxytabs.css" rel="stylesheet" type="text/css" />
<style type="text/css">
<!--
.header {
	font-family: Verdana, Arial, Helvetica, sans-serif;
	font-size: 12pt;
	color: #222222;
}
-->
</style>
</head>

<body>
<table width="800" border="0">
    <tr>
      <td colspan="3">
        <form method="get" action="http://www.google.com/search">
          <div align="right">
            <input type="text"   name="q" size="25"
              maxlength="255" value="" />
            <input type="submit" value="Search" />
            <input type="hidden" name="sitesearch" value="makingthings.com/ref/firmware/html" />
          </div>
        </form>
       </td>
    </tr>
    <tr>
      <td><div align="center"><a href="http://www.makingthings.com">
				<img src="../resources/logo_brown_medium.png" alt="MakingThings"
									width="200" height="78" border="0" align="middle" longdesc="http://www.makingthings.com" /></a></div></td>
				<td><div align="center" class="header">
      		Make Controller Kit <br />
          Firmware API
      </div></td>
      <td><div align="center"><a href="http://www.makezine.com">
					<img src="../resources/make_logo.png" alt="MAKE Zine" 
										width="164" height="73" border="0" align="middle" longdesc="http://www.makezine.com" /></a></div></td>
    </tr>
</table>
</body>
</html>
<!-- Generated by Doxygen 1.5.4 -->
<script type="text/javascript">
<!--
function changeDisplayState (e){
  var num=this.id.replace(/[^[0-9]/g,'');
  var button=this.firstChild;
  var sectionDiv=document.getElementById('dynsection'+num);
  if (sectionDiv.style.display=='none'||sectionDiv.style.display==''){
    sectionDiv.style.display='block';
    button.src='open.gif';
  }else{
    sectionDiv.style.display='none';
    button.src='closed.gif';
  }
}
function initDynSections(){
  var divs=document.getElementsByTagName('div');
  var sectionCounter=1;
  for(var i=0;i<divs.length-1;i++){
    if(divs[i].className=='dynheader'&&divs[i+1].className=='dynsection'){
      var header=divs[i];
      var section=divs[i+1];
      var button=header.firstChild;
      if (button!='IMG'){
        divs[i].insertBefore(document.createTextNode(' '),divs[i].firstChild);
        button=document.createElement('img');
        divs[i].insertBefore(button,divs[i].firstChild);
      }
      header.style.cursor='pointer';
      header.onclick=changeDisplayState;
      header.id='dynheader'+sectionCounter;
      button.src='closed.gif';
      section.id='dynsection'+sectionCounter;
      section.style.display='none';
      section.style.marginLeft='14px';
      sectionCounter++;
    }
  }
}
window.onload = initDynSections;
-->
</script>
<div class="tabs">
  <ul>
    <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
    <li><a href="modules.html"><span>Modules</span></a></li>
    <li><a href="classes.html"><span>Data&nbsp;Structures</span></a></li>
    <li class="current"><a href="files.html"><span>Files</span></a></li>
    <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
  </ul>
</div>
<h1>rtos.c</h1><a href="rtos_8c.html">Go to the documentation of this file.</a><div class="fragment"><pre class="fragment"><a name="l00001"></a>00001 <span class="comment">/*********************************************************************************</span>
<a name="l00002"></a>00002 <span class="comment"></span>
<a name="l00003"></a>00003 <span class="comment"> Copyright 2006 MakingThings</span>
<a name="l00004"></a>00004 <span class="comment"></span>
<a name="l00005"></a>00005 <span class="comment"> Licensed under the Apache License, </span>
<a name="l00006"></a>00006 <span class="comment"> Version 2.0 (the "License"); you may not use this file except in compliance </span>
<a name="l00007"></a>00007 <span class="comment"> with the License. You may obtain a copy of the License at</span>
<a name="l00008"></a>00008 <span class="comment"></span>
<a name="l00009"></a>00009 <span class="comment"> http://www.apache.org/licenses/LICENSE-2.0 </span>
<a name="l00010"></a>00010 <span class="comment"> </span>
<a name="l00011"></a>00011 <span class="comment"> Unless required by applicable law or agreed to in writing, software distributed</span>
<a name="l00012"></a>00012 <span class="comment"> under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR</span>
<a name="l00013"></a>00013 <span class="comment"> CONDITIONS OF ANY KIND, either express or implied. See the License for</span>
<a name="l00014"></a>00014 <span class="comment"> the specific language governing permissions and limitations under the License.</span>
<a name="l00015"></a>00015 <span class="comment"></span>
<a name="l00016"></a>00016 <span class="comment">*********************************************************************************/</span>
<a name="l00017"></a>00017 <span class="comment"></span>
<a name="l00018"></a>00018 <span class="comment">/** \file rtos.c  </span>
<a name="l00019"></a>00019 <span class="comment">  RTOS - Real Time Operating System.</span>
<a name="l00020"></a>00020 <span class="comment">  Functions to work within FreeRTOS on the Make Controller Board.</span>
<a name="l00021"></a>00021 <span class="comment">*/</span>
<a name="l00022"></a>00022 
<a name="l00023"></a>00023 <span class="comment">/* Scheduler includes. */</span>
<a name="l00024"></a>00024 <span class="preprocessor">#include "FreeRTOS.h"</span>
<a name="l00025"></a>00025 <span class="preprocessor">#include "task.h"</span>
<a name="l00026"></a>00026 <span class="preprocessor">#include "rtos.h"</span>
<a name="l00027"></a>00027 <span class="preprocessor">#include "string.h"</span>
<a name="l00028"></a>00028 <span class="preprocessor">#include "queue.h"</span>
<a name="l00029"></a>00029 <span class="preprocessor">#include "semphr.h"</span>
<a name="l00030"></a>00030 
<a name="l00031"></a>00031 <span class="keywordtype">void</span>* findTask( <span class="keywordtype">char</span> *taskName, <span class="keywordtype">int</span> taskID );
<a name="l00032"></a>00032 <span class="keywordtype">void</span>* iterateForNextTask( <span class="keywordtype">void</span>** lowTask, <span class="keywordtype">int</span>* lowID, <span class="keywordtype">void</span>** highTask, <span class="keywordtype">int</span>* highID, <span class="keywordtype">int</span> currentID, xList* pxList );
<a name="l00033"></a>00033 <span class="keywordtype">void</span>* iterateByID( <span class="keywordtype">int</span> <span class="keywordtype">id</span>, xList* pxList );
<a name="l00034"></a>00034 <span class="keywordtype">void</span>* iterateByName( <span class="keywordtype">char</span>* taskName, xList* pxList );
<a name="l00035"></a>00035 <span class="keywordtype">void</span>* TaskGetNext_internal( <span class="keywordtype">void</span>* task );
<a name="l00036"></a>00036 <span class="comment"></span>
<a name="l00037"></a>00037 <span class="comment">/** \defgroup RTOS RTOS</span>
<a name="l00038"></a>00038 <span class="comment">  The RTOS subsystem provides a real-time operating system (RTOS) for the MAKE Controller.</span>
<a name="l00039"></a>00039 <span class="comment">  Currently, the Make Controller uses FreeRTOS, an open source Real-Time Operating System.  It implements a scheduler that </span>
<a name="l00040"></a>00040 <span class="comment">  gives time to "concurrent" tasks according to their given priority.  It allows programmers to </span>
<a name="l00041"></a>00041 <span class="comment">  focus on programming each process on the board separately, letting the RTOS </span>
<a name="l00042"></a>00042 <span class="comment">  determine when each of those tasks should be given processor time.</span>
<a name="l00043"></a>00043 <span class="comment">  </span>
<a name="l00044"></a>00044 <span class="comment">  More info at http://www.freertos.org</span>
<a name="l00045"></a>00045 <span class="comment">* \ingroup Controller</span>
<a name="l00046"></a>00046 <span class="comment">*/</span>
<a name="l00047"></a>00047 <span class="comment"></span>
<a name="l00048"></a>00048 <span class="comment">/** \defgroup Tasks Tasks</span>
<a name="l00049"></a>00049 <span class="comment">  The individual "programs" that make up your application.</span>
<a name="l00050"></a>00050 <span class="comment">  Tasks can all be written separately and the RTOS will take of switching between them, </span>
<a name="l00051"></a>00051 <span class="comment">  making sure they all get the processing time they need.  Each task is implemented as a continuous loop, and</span>
<a name="l00052"></a>00052 <span class="comment">  all tasks have the same signature:</span>
<a name="l00053"></a>00053 <span class="comment">  \code void MyTask( void* parameters) \endcode</span>
<a name="l00054"></a>00054 <span class="comment">  The void* parameters is a value that can be passed in at the time the task is created.  Make sure that you put your task</span>
<a name="l00055"></a>00055 <span class="comment">  to sleep when it's not doing anything so that other tasks can get time as well.  Otherwise, the Controller will lock up</span>
<a name="l00056"></a>00056 <span class="comment">  and none of the other tasks will run.</span>
<a name="l00057"></a>00057 <span class="comment">  </span>
<a name="l00058"></a>00058 <span class="comment">  \par Example</span>
<a name="l00059"></a>00059 <span class="comment">  \code</span>
<a name="l00060"></a>00060 <span class="comment">  void MyTask( void* p )</span>
<a name="l00061"></a>00061 <span class="comment">  {</span>
<a name="l00062"></a>00062 <span class="comment">    // some initialization here</span>
<a name="l00063"></a>00063 <span class="comment">    int newVal = 0;</span>
<a name="l00064"></a>00064 <span class="comment">    </span>
<a name="l00065"></a>00065 <span class="comment">    // then just sit in our loop</span>
<a name="l00066"></a>00066 <span class="comment">    // we're going to turn an LED on whenever an AnalogIn is over a certain value </span>
<a name="l00067"></a>00067 <span class="comment">    while( 1 )</span>
<a name="l00068"></a>00068 <span class="comment">    {</span>
<a name="l00069"></a>00069 <span class="comment">      newVal = AnalogIn_GetValue( 1 );</span>
<a name="l00070"></a>00070 <span class="comment">      if( newVal &lt; 512 )</span>
<a name="l00071"></a>00071 <span class="comment">        AppLed_SetState( 0, 1 );</span>
<a name="l00072"></a>00072 <span class="comment">      else</span>
<a name="l00073"></a>00073 <span class="comment">        AppLed_SetState( 0, 0 );</span>
<a name="l00074"></a>00074 <span class="comment">      Sleep( 100 ); // wait for 100 milliseconds, allowing other tasks to do their thing</span>
<a name="l00075"></a>00075 <span class="comment">    }</span>
<a name="l00076"></a>00076 <span class="comment">  }</span>
<a name="l00077"></a>00077 <span class="comment">  \endcode</span>
<a name="l00078"></a>00078 <span class="comment">  </span>
<a name="l00079"></a>00079 <span class="comment">  Notice we don't need to include anything about Ethernet or USB communication, or anything else that might</span>
<a name="l00080"></a>00080 <span class="comment">  be going on.  These are taken care of elsewhere by the RTOS, allowing us to focus on our LED blinking.</span>
<a name="l00081"></a>00081 <span class="comment">  </span>
<a name="l00082"></a>00082 <span class="comment">  More info at http://www.freertos.org</span>
<a name="l00083"></a>00083 <span class="comment">* \ingroup RTOS</span>
<a name="l00084"></a>00084 <span class="comment">* @{</span>
<a name="l00085"></a>00085 <span class="comment">*/</span>
<a name="l00086"></a>00086 <span class="comment"></span>
<a name="l00087"></a>00087 <span class="comment">/** </span>
<a name="l00088"></a>00088 <span class="comment">  Put a task to sleep for a given number of milliseconds.</span>
<a name="l00089"></a>00089 <span class="comment">  This lets the processor give time to other tasks.  You'll always want to include some amount of Sleep( ) in your tasks</span>
<a name="l00090"></a>00090 <span class="comment">  to avoid locking up the Controller.</span>
<a name="l00091"></a>00091 <span class="comment">  @param timems An integer specifying how long to sleep in milliseconds.</span>
<a name="l00092"></a>00092 <span class="comment">  </span>
<a name="l00093"></a>00093 <span class="comment">\par Example</span>
<a name="l00094"></a>00094 <span class="comment">\code</span>
<a name="l00095"></a>00095 <span class="comment">void MyTask( void *p) // in your task</span>
<a name="l00096"></a>00096 <span class="comment">{</span>
<a name="l00097"></a>00097 <span class="comment">  while( 1 )</span>
<a name="l00098"></a>00098 <span class="comment">  {</span>
<a name="l00099"></a>00099 <span class="comment">    Led_SetState( 0 ); // turn the LED off</span>
<a name="l00100"></a>00100 <span class="comment">    Sleep( 900 ); // leave it off for 900 milliseconds</span>
<a name="l00101"></a>00101 <span class="comment">    Led_SetState( 1 ); // turn the LED on</span>
<a name="l00102"></a>00102 <span class="comment">    Sleep( 10 ); // leave it on for 10 milliseconds</span>
<a name="l00103"></a>00103 <span class="comment">  }</span>
<a name="l00104"></a>00104 <span class="comment">}</span>
<a name="l00105"></a>00105 <span class="comment">\endcode</span>
<a name="l00106"></a>00106 <span class="comment">*/</span>
<a name="l00107"></a><a class="code" href="group___tasks.html#g9a64a7c0e24f257826103d1d1bbb44fa">00107</a> <span class="keywordtype">void</span> <a class="code" href="group___tasks.html#g9a64a7c0e24f257826103d1d1bbb44fa" title="Put a task to sleep for a given number of milliseconds.">Sleep</a>( <span class="keywordtype">int</span> timems )
<a name="l00108"></a>00108 {
<a name="l00109"></a>00109   vTaskDelay( timems / portTICK_RATE_MS );
<a name="l00110"></a>00110 }
<a name="l00111"></a>00111 <span class="comment"></span>
<a name="l00112"></a>00112 <span class="comment">/** </span>
<a name="l00113"></a>00113 <span class="comment">  Give up the remaining time allotted to this task by the processor.</span>
<a name="l00114"></a>00114 <span class="comment">  The presently running task immeidately gives up the remaining time it has in the current timeslice </span>
<a name="l00115"></a>00115 <span class="comment">  so that other tasks can run.  While Sleep() will wait the specified number of milliseconds </span>
<a name="l00116"></a>00116 <span class="comment">  before continuing, TaskYield() will cause the task to take processor time again </span>
<a name="l00117"></a>00117 <span class="comment">  as soon as it's available.</span>
<a name="l00118"></a>00118 <span class="comment">*/</span>
<a name="l00119"></a><a class="code" href="group___tasks.html#gbe9e0304997a15f46d9eae37be16e3f2">00119</a> <span class="keywordtype">void</span> <a class="code" href="group___tasks.html#gbe9e0304997a15f46d9eae37be16e3f2" title="Give up the remaining time allotted to this task by the processor.">TaskYield</a>( )
<a name="l00120"></a>00120 {
<a name="l00121"></a>00121   taskYIELD(); 
<a name="l00122"></a>00122 }
<a name="l00123"></a>00123 <span class="comment"></span>
<a name="l00124"></a>00124 <span class="comment">/** </span>
<a name="l00125"></a>00125 <span class="comment">  Create a new task.</span>
<a name="l00126"></a>00126 <span class="comment">  </span>
<a name="l00127"></a>00127 <span class="comment">  When creating a new task, be sure that you allocate it enough stack space.  A task must have enough stack space </span>
<a name="l00128"></a>00128 <span class="comment">  to load any of the potential data structures it will be working with, otherwise it will die and the Controller will crash.</span>
<a name="l00129"></a>00129 <span class="comment">  </span>
<a name="l00130"></a>00130 <span class="comment">  Since FreeRTOS is pre-emptive, higher priority tasks will get processor time before lower priority tasks.  The priority</span>
<a name="l00131"></a>00131 <span class="comment">  level is a bit arbitrary, but choose something that makes sense in relation to the other tasks you have running. Always be </span>
<a name="l00132"></a>00132 <span class="comment">  sure to block a task when possible, in order to give processor time to other tasks.</span>
<a name="l00133"></a>00133 <span class="comment">  @param taskCode A pointer to the function that will run when the task starts.</span>
<a name="l00134"></a>00134 <span class="comment">  @param name A character string containing the name of the task.</span>
<a name="l00135"></a>00135 <span class="comment">  @param stackDepth An integer specifying in bytes the size of the task's stack.</span>
<a name="l00136"></a>00136 <span class="comment">  @param parameters A void* parameter which will be passed into the task at create time.</span>
<a name="l00137"></a>00137 <span class="comment">  @param priority An integer specifying the task's priority (0 lowest - 7 highest priority).</span>
<a name="l00138"></a>00138 <span class="comment">  @return A pointer to the handle for the newly created task, or NULL if it didn't succeed.</span>
<a name="l00139"></a>00139 <span class="comment">  @see TaskDelete( )</span>
<a name="l00140"></a>00140 <span class="comment">  </span>
<a name="l00141"></a>00141 <span class="comment">\par Example</span>
<a name="l00142"></a>00142 <span class="comment">\code</span>
<a name="l00143"></a>00143 <span class="comment">// create the task MyTask, called "Me", with a stack of 1000 bytes, no parameters, at priority 1</span>
<a name="l00144"></a>00144 <span class="comment">void *taskPtr = TaskCreate( MyTask, "Me", 1000, 0, 1 );</span>
<a name="l00145"></a>00145 <span class="comment"></span>
<a name="l00146"></a>00146 <span class="comment">void MyTask( void *p) // in your task</span>
<a name="l00147"></a>00147 <span class="comment">{</span>
<a name="l00148"></a>00148 <span class="comment">  // set up any variables that you'll need</span>
<a name="l00149"></a>00149 <span class="comment">  int counter = 0;</span>
<a name="l00150"></a>00150 <span class="comment">  // then start your continuous loop</span>
<a name="l00151"></a>00151 <span class="comment">  while( 1 )</span>
<a name="l00152"></a>00152 <span class="comment">  {</span>
<a name="l00153"></a>00153 <span class="comment">    counter++;</span>
<a name="l00154"></a>00154 <span class="comment">    Sleep( 100 );</span>
<a name="l00155"></a>00155 <span class="comment">  }</span>
<a name="l00156"></a>00156 <span class="comment">}</span>
<a name="l00157"></a>00157 <span class="comment">\endcode</span>
<a name="l00158"></a>00158 <span class="comment">*/</span>
<a name="l00159"></a><a class="code" href="group___tasks.html#g784f87fb45eebb76d07478036ed228d3">00159</a> <span class="keywordtype">void</span>* <a class="code" href="group___tasks.html#g784f87fb45eebb76d07478036ed228d3" title="Create a new task.">TaskCreate</a>( <span class="keywordtype">void</span> (taskCode)( <span class="keywordtype">void</span>*), <span class="keywordtype">char</span>* name, <span class="keywordtype">int</span> stackDepth, <span class="keywordtype">void</span>* parameters, <span class="keywordtype">int</span> priority )
<a name="l00160"></a>00160 {
<a name="l00161"></a>00161   <span class="keywordtype">void</span>* taskHandle;
<a name="l00162"></a>00162   <span class="keywordflow">if</span>( xTaskCreate( taskCode, (<span class="keywordtype">signed</span> <span class="keywordtype">char</span>*)name, ( stackDepth &gt;&gt; 2 ), parameters, priority, &amp;taskHandle ) == 1 )
<a name="l00163"></a>00163     <span class="keywordflow">return</span> taskHandle;
<a name="l00164"></a>00164   <span class="keywordflow">else</span>
<a name="l00165"></a>00165     <span class="keywordflow">return</span> NULL;
<a name="l00166"></a>00166 }
<a name="l00167"></a>00167 <span class="comment"></span>
<a name="l00168"></a>00168 <span class="comment">/** </span>
<a name="l00169"></a>00169 <span class="comment">  Delete an existing task.</span>
<a name="l00170"></a>00170 <span class="comment">  TaskCreate( ) returns a pointer to the newly created task.  You'll need to hang onto this pointer in order to delete the task.</span>
<a name="l00171"></a>00171 <span class="comment">  @param task A pointer to the handle of the task to be deleted.</span>
<a name="l00172"></a>00172 <span class="comment">  </span>
<a name="l00173"></a>00173 <span class="comment">\par Example</span>
<a name="l00174"></a>00174 <span class="comment">\code</span>
<a name="l00175"></a>00175 <span class="comment">void *taskPtr = TaskCreate( MyTask, "Me", 1000, 0, 1 ); // create a new task</span>
<a name="l00176"></a>00176 <span class="comment">// ... run the task ...</span>
<a name="l00177"></a>00177 <span class="comment">TaskDelete( taskPtr ); // then delete it</span>
<a name="l00178"></a>00178 <span class="comment">\endcode</span>
<a name="l00179"></a>00179 <span class="comment">*/</span>
<a name="l00180"></a><a class="code" href="group___tasks.html#g5bc41573c59208d32d999e2f394ad3ce">00180</a> <span class="keywordtype">void</span> <a class="code" href="group___tasks.html#g5bc41573c59208d32d999e2f394ad3ce" title="Delete an existing task.">TaskDelete</a>( <span class="keywordtype">void</span>* task )
<a name="l00181"></a>00181 {
<a name="l00182"></a>00182   vTaskDelete( task );
<a name="l00183"></a>00183 }
<a name="l00184"></a>00184 <span class="comment"></span>
<a name="l00185"></a>00185 <span class="comment">/** </span>
<a name="l00186"></a>00186 <span class="comment">  Specify that a task is entering a period during which it should not be interrupted.  </span>
<a name="l00187"></a>00187 <span class="comment">  Call this from within your task.  Be sure to minimize use of this, and to call TaskExitCritical() as soon as the </span>
<a name="l00188"></a>00188 <span class="comment">  task has completed its critical stage.  Other tasks can't get any processor time while in</span>
<a name="l00189"></a>00189 <span class="comment">  this state, and performance might be compromised.</span>
<a name="l00190"></a>00190 <span class="comment">  @see TaskExitCritical( )</span>
<a name="l00191"></a>00191 <span class="comment">*/</span>
<a name="l00192"></a><a class="code" href="group___tasks.html#gd02e088c48f69fd07cf3157bcceb01b7">00192</a> <span class="keywordtype">void</span>  <a class="code" href="group___tasks.html#gd02e088c48f69fd07cf3157bcceb01b7" title="Specify that a task is entering a period during which it should not be interrupted...">TaskEnterCritical</a>( )
<a name="l00193"></a>00193 {
<a name="l00194"></a>00194   taskENTER_CRITICAL();
<a name="l00195"></a>00195 }
<a name="l00196"></a>00196 <span class="comment"></span>
<a name="l00197"></a>00197 <span class="comment">/** </span>
<a name="l00198"></a>00198 <span class="comment">  Specify that a task is exiting a critical period, in response to TaskEnterCritical().</span>
<a name="l00199"></a>00199 <span class="comment">  Once the task exits a critical period, FreeRTOS will resume switching this task as usual.</span>
<a name="l00200"></a>00200 <span class="comment">  @see TaskEnterCritical( )</span>
<a name="l00201"></a>00201 <span class="comment">*/</span>
<a name="l00202"></a><a class="code" href="group___tasks.html#g0911fd273992ff4dec66d096a9dc3257">00202</a> <span class="keywordtype">void</span>  <a class="code" href="group___tasks.html#g0911fd273992ff4dec66d096a9dc3257" title="Specify that a task is exiting a critical period, in response to TaskEnterCritical()...">TaskExitCritical</a>( )
<a name="l00203"></a>00203 {
<a name="l00204"></a>00204   taskEXIT_CRITICAL();
<a name="l00205"></a>00205 }
<a name="l00206"></a>00206 <span class="comment"></span>
<a name="l00207"></a>00207 <span class="comment">/** </span>
<a name="l00208"></a>00208 <span class="comment">Check how much stack is available for a given task.</span>
<a name="l00209"></a>00209 <span class="comment">When a task is created, it is initialized with a stack depth.  This function will return the</span>
<a name="l00210"></a>00210 <span class="comment">numbers of bytes available from that initial allocation.</span>
<a name="l00211"></a>00211 <span class="comment">@return An integer specifying the available stack in bytes.</span>
<a name="l00212"></a>00212 <span class="comment">@see TaskGetStackAllocated( )</span>
<a name="l00213"></a>00213 <span class="comment"></span>
<a name="l00214"></a>00214 <span class="comment">\par Example</span>
<a name="l00215"></a>00215 <span class="comment">\code</span>
<a name="l00216"></a>00216 <span class="comment">void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 ); // create a new task</span>
<a name="l00217"></a>00217 <span class="comment">int freeBytes = TaskGetRemainingStack( taskPtr ); // check how much of the task's stack has been used</span>
<a name="l00218"></a>00218 <span class="comment">\endcode</span>
<a name="l00219"></a>00219 <span class="comment">*/</span>
<a name="l00220"></a><a class="code" href="group___tasks.html#gbce595eac3d0cfb96b1cd9037a613ef8">00220</a> <span class="keywordtype">int</span> <a class="code" href="group___tasks.html#gbce595eac3d0cfb96b1cd9037a613ef8" title="Check how much stack is available for a given task.">TaskGetRemainingStack</a>( <span class="keywordtype">void</span>* task )
<a name="l00221"></a>00221 {
<a name="l00222"></a>00222   <span class="keywordflow">if</span>( task != NULL )
<a name="l00223"></a>00223     <span class="keywordflow">return</span> usVoidTaskCheckFreeStackSpace( task );
<a name="l00224"></a>00224   <span class="keywordflow">else</span>
<a name="l00225"></a>00225     <span class="keywordflow">return</span> <a class="code" href="group___error.html#g2cd3e8ce9b1d59bb5bf2972ab35a8b48" title="Not enough memory available.">CONTROLLER_ERROR_INSUFFICIENT_RESOURCES</a>;
<a name="l00226"></a>00226 }
<a name="l00227"></a>00227 <span class="comment"></span>
<a name="l00228"></a>00228 <span class="comment">/** </span>
<a name="l00229"></a>00229 <span class="comment">  Get a pointer to a task by its name.</span>
<a name="l00230"></a>00230 <span class="comment">  When a task is created, it is initialized with a name.  If you don't have a pointer to the task itself</span>
<a name="l00231"></a>00231 <span class="comment">  but you know its name, you can still get a reference to the task.  This is a costly function, as it</span>
<a name="l00232"></a>00232 <span class="comment">  shuts down the scheduler to search for the task, so it should really only be used in a debug setting.</span>
<a name="l00233"></a>00233 <span class="comment">  @param taskName A character string specifying the name of the task to find.</span>
<a name="l00234"></a>00234 <span class="comment">  @return A pointer to the task, or NULL if the task was not found.</span>
<a name="l00235"></a>00235 <span class="comment">  @see getTaskByID()</span>
<a name="l00236"></a>00236 <span class="comment">  </span>
<a name="l00237"></a>00237 <span class="comment">\par Example</span>
<a name="l00238"></a>00238 <span class="comment">\code</span>
<a name="l00239"></a>00239 <span class="comment">TaskCreate( MyTask, "Mine", 1000, 0, 1 ); // a task has been created, but we don't have a pointer to it</span>
<a name="l00240"></a>00240 <span class="comment">void *taskPtr = getTaskByName( "Mine" ); // but we can still get a pointer to it by its name</span>
<a name="l00241"></a>00241 <span class="comment">\endcode</span>
<a name="l00242"></a>00242 <span class="comment">*/</span>
<a name="l00243"></a><a class="code" href="group___tasks.html#gdd4c687d4df17e7eee740e3e8bc103c8">00243</a> <span class="keywordtype">void</span>* <a class="code" href="group___tasks.html#gdd4c687d4df17e7eee740e3e8bc103c8" title="Get a pointer to a task by its name.">getTaskByName</a>( <span class="keywordtype">char</span> *taskName )
<a name="l00244"></a>00244 {
<a name="l00245"></a>00245   <span class="keywordtype">void</span> *tcb = NULL;
<a name="l00246"></a>00246   vTaskSuspendAll();
<a name="l00247"></a>00247   {
<a name="l00248"></a>00248     tcb = findTask( taskName, -1 );
<a name="l00249"></a>00249   }
<a name="l00250"></a>00250   xTaskResumeAll();
<a name="l00251"></a>00251   <span class="keywordflow">return</span> tcb;
<a name="l00252"></a>00252 }
<a name="l00253"></a>00253 <span class="comment"></span>
<a name="l00254"></a>00254 <span class="comment">/** </span>
<a name="l00255"></a>00255 <span class="comment">  Get a pointer to a task by its ID number.</span>
<a name="l00256"></a>00256 <span class="comment">  Each task is given a unique ID number by freeRTOS.  If you know this number, but don't have a pointer</span>
<a name="l00257"></a>00257 <span class="comment">  to the task, use this function to get a pointer to the task itself.  This is a costly function, as it</span>
<a name="l00258"></a>00258 <span class="comment">  shuts down the scheduler to search for the task, so it should really only be used in a debug setting.</span>
<a name="l00259"></a>00259 <span class="comment">  @param taskID An integer specifying the unique ID number given to the task by FreeRTOS</span>
<a name="l00260"></a>00260 <span class="comment">  @return A pointer to the task, or NULL if the task was not found.</span>
<a name="l00261"></a>00261 <span class="comment">  @see TaskGetIDNumber( )</span>
<a name="l00262"></a>00262 <span class="comment">*/</span>
<a name="l00263"></a><a class="code" href="group___tasks.html#ge92ca2261fff9550cc18ac991afafd01">00263</a> <span class="keywordtype">void</span>* <a class="code" href="group___tasks.html#ge92ca2261fff9550cc18ac991afafd01" title="Get a pointer to a task by its ID number.">getTaskByID</a>( <span class="keywordtype">int</span> taskID )
<a name="l00264"></a>00264 {
<a name="l00265"></a>00265   <span class="keywordtype">void</span>* tcb = NULL;
<a name="l00266"></a>00266   vTaskSuspendAll();
<a name="l00267"></a>00267   {
<a name="l00268"></a>00268     tcb = findTask( NULL, taskID );
<a name="l00269"></a>00269   }
<a name="l00270"></a>00270   xTaskResumeAll();
<a name="l00271"></a>00271   <span class="keywordflow">return</span> tcb;
<a name="l00272"></a>00272 }
<a name="l00273"></a>00273 <span class="comment"></span>
<a name="l00274"></a>00274 <span class="comment">/** </span>
<a name="l00275"></a>00275 <span class="comment">  Get the priority of a task.</span>
<a name="l00276"></a>00276 <span class="comment">  When a task is created, it's given a priority from 1-7.  Use this function to get the task's priority</span>
<a name="l00277"></a>00277 <span class="comment">  after it has been created.</span>
<a name="l00278"></a>00278 <span class="comment">  @param task A pointer to the task.</span>
<a name="l00279"></a>00279 <span class="comment">  @return An integer specifying the task's priority</span>
<a name="l00280"></a>00280 <span class="comment">  </span>
<a name="l00281"></a>00281 <span class="comment">\par Example</span>
<a name="l00282"></a>00282 <span class="comment">\code</span>
<a name="l00283"></a>00283 <span class="comment">void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 );</span>
<a name="l00284"></a>00284 <span class="comment">int priority = TaskGetPriority( taskPtr ); // will return 1</span>
<a name="l00285"></a>00285 <span class="comment">\endcode</span>
<a name="l00286"></a>00286 <span class="comment">*/</span>
<a name="l00287"></a><a class="code" href="group___tasks.html#g0b8075007b824b2295dc5d3453a372fb">00287</a> <span class="keywordtype">int</span> <a class="code" href="group___tasks.html#g0b8075007b824b2295dc5d3453a372fb" title="Get the priority of a task.">TaskGetPriority</a>( <span class="keywordtype">void</span>* task )
<a name="l00288"></a>00288 {
<a name="l00289"></a>00289   <span class="keywordflow">return</span> xTaskGetPriority( task );
<a name="l00290"></a>00290 }
<a name="l00291"></a>00291 <span class="comment"></span>
<a name="l00292"></a>00292 <span class="comment">/** </span>
<a name="l00293"></a>00293 <span class="comment">  Get the ID number of a task.</span>
<a name="l00294"></a>00294 <span class="comment">  FreeRTOS assigns each task a unique ID number.  Use this function to retrieve a particular task's ID number.</span>
<a name="l00295"></a>00295 <span class="comment">  Task ID numbers are not necessarily sequential.</span>
<a name="l00296"></a>00296 <span class="comment">  @param task A pointer to the task.</span>
<a name="l00297"></a>00297 <span class="comment">  @return An integer specifying the task's unique ID within freeRTOS, or -1 on fail.</span>
<a name="l00298"></a>00298 <span class="comment">  </span>
<a name="l00299"></a>00299 <span class="comment">\par Example</span>
<a name="l00300"></a>00300 <span class="comment">\code</span>
<a name="l00301"></a>00301 <span class="comment">void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 );</span>
<a name="l00302"></a>00302 <span class="comment">int id = TaskGetIDNumber( taskPtr );</span>
<a name="l00303"></a>00303 <span class="comment">\endcode</span>
<a name="l00304"></a>00304 <span class="comment">*/</span>
<a name="l00305"></a><a class="code" href="group___tasks.html#g39806aeaa7dd24062f13c3118ca1b990">00305</a> <span class="keywordtype">int</span> <a class="code" href="group___tasks.html#g39806aeaa7dd24062f13c3118ca1b990" title="Get the ID number of a task.">TaskGetIDNumber</a>( <span class="keywordtype">void</span>* task )
<a name="l00306"></a>00306 {
<a name="l00307"></a>00307   <span class="keywordflow">return</span> xTaskGetIDNumber( task );
<a name="l00308"></a>00308 }
<a name="l00309"></a>00309 <span class="comment"></span>
<a name="l00310"></a>00310 <span class="comment">/** </span>
<a name="l00311"></a>00311 <span class="comment">  Get the name of a task.</span>
<a name="l00312"></a>00312 <span class="comment">  Read back the name a task was given when it was created.</span>
<a name="l00313"></a>00313 <span class="comment">  @param task A pointer to the task.</span>
<a name="l00314"></a>00314 <span class="comment">  @return The task's name as a string</span>
<a name="l00315"></a>00315 <span class="comment">  </span>
<a name="l00316"></a>00316 <span class="comment">\par Example</span>
<a name="l00317"></a>00317 <span class="comment">\code</span>
<a name="l00318"></a>00318 <span class="comment">void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 );</span>
<a name="l00319"></a>00319 <span class="comment">char* name = TaskGetName( taskPtr ); // will return "Mine"</span>
<a name="l00320"></a>00320 <span class="comment">\endcode</span>
<a name="l00321"></a>00321 <span class="comment">*/</span>
<a name="l00322"></a><a class="code" href="group___tasks.html#ga15296e2b927abaadce9ed3028917afd">00322</a> <span class="keywordtype">char</span>* <a class="code" href="group___tasks.html#ga15296e2b927abaadce9ed3028917afd" title="Get the name of a task.">TaskGetName</a>( <span class="keywordtype">void</span>* task )
<a name="l00323"></a>00323 {
<a name="l00324"></a>00324   <span class="keywordflow">return</span> (<span class="keywordtype">char</span>*)xTaskGetName( task );
<a name="l00325"></a>00325 }
<a name="l00326"></a>00326 <span class="comment"></span>
<a name="l00327"></a>00327 <span class="comment">/** </span>
<a name="l00328"></a>00328 <span class="comment">  Read the amount of stack initially allocated for a task.</span>
<a name="l00329"></a>00329 <span class="comment">  Each task is allocated a certain amount of stack space when it's created.  Use this function to</span>
<a name="l00330"></a>00330 <span class="comment">  determine how much stack space a task was originally given.</span>
<a name="l00331"></a>00331 <span class="comment">  @param task A pointer to the task.</span>
<a name="l00332"></a>00332 <span class="comment">  @return An integer specifying the amount of stack, in bytes, that this task was allocated.</span>
<a name="l00333"></a>00333 <span class="comment">  @see TaskGetRemainingStack( )</span>
<a name="l00334"></a>00334 <span class="comment">  </span>
<a name="l00335"></a>00335 <span class="comment">\par Example</span>
<a name="l00336"></a>00336 <span class="comment">\code</span>
<a name="l00337"></a>00337 <span class="comment">void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 );</span>
<a name="l00338"></a>00338 <span class="comment">int stack = TaskGetStackAllocated( taskPtr ); // will return 1000</span>
<a name="l00339"></a>00339 <span class="comment">\endcode</span>
<a name="l00340"></a>00340 <span class="comment">*/</span>
<a name="l00341"></a><a class="code" href="group___tasks.html#g7bbfe88356db1ef137b85881a1074e29">00341</a> <span class="keywordtype">int</span> <a class="code" href="group___tasks.html#g7bbfe88356db1ef137b85881a1074e29" title="Read the amount of stack initially allocated for a task.">TaskGetStackAllocated</a>( <span class="keywordtype">void</span>* task )
<a name="l00342"></a>00342 {
<a name="l00343"></a>00343   <span class="keywordflow">return</span> xTaskGetStackAllocated( task );
<a name="l00344"></a>00344 }
<a name="l00345"></a>00345 <span class="comment"></span>
<a name="l00346"></a>00346 <span class="comment">/** </span>
<a name="l00347"></a>00347 <span class="comment">  Get a pointer to the task that's currently running.</span>
<a name="l00348"></a>00348 <span class="comment">  @return A pointer to the task that's currently running.</span>
<a name="l00349"></a>00349 <span class="comment">  </span>
<a name="l00350"></a>00350 <span class="comment">\par Example</span>
<a name="l00351"></a>00351 <span class="comment">\code</span>
<a name="l00352"></a>00352 <span class="comment">void *currentTask = TaskGetCurrent( );</span>
<a name="l00353"></a>00353 <span class="comment">\endcode</span>
<a name="l00354"></a>00354 <span class="comment">*/</span>
<a name="l00355"></a><a class="code" href="group___tasks.html#g8026e84bd2096796b7899a35dee6f060">00355</a> <span class="keywordtype">void</span>* <a class="code" href="group___tasks.html#g8026e84bd2096796b7899a35dee6f060" title="Get a pointer to the task that&amp;#39;s currently running.">TaskGetCurrent</a>( )
<a name="l00356"></a>00356 {
<a name="l00357"></a>00357   <span class="keywordflow">return</span> xTaskGetCurrentTaskHandle( );
<a name="l00358"></a>00358 }
<a name="l00359"></a>00359 <span class="comment"></span>
<a name="l00360"></a>00360 <span class="comment">/** </span>
<a name="l00361"></a>00361 <span class="comment">  Read the highest priority being used by any existing task.</span>
<a name="l00362"></a>00362 <span class="comment">  @return An integer specifying the priority.</span>
<a name="l00363"></a>00363 <span class="comment">  </span>
<a name="l00364"></a>00364 <span class="comment">\par Example</span>
<a name="l00365"></a>00365 <span class="comment">\code</span>
<a name="l00366"></a>00366 <span class="comment">int highestPriority = TaskGetTopPriorityUsed( );</span>
<a name="l00367"></a>00367 <span class="comment">\endcode</span>
<a name="l00368"></a>00368 <span class="comment">*/</span>
<a name="l00369"></a><a class="code" href="group___tasks.html#g4f0b02fb8a36b62908efd6b649339d19">00369</a> <span class="keywordtype">int</span> <a class="code" href="group___tasks.html#g4f0b02fb8a36b62908efd6b649339d19" title="Read the highest priority being used by any existing task.">TaskGetTopPriorityUsed</a>( )
<a name="l00370"></a>00370 {
<a name="l00371"></a>00371   <span class="keywordflow">return</span> xTaskGetTopUsedPriority( );
<a name="l00372"></a>00372 }
<a name="l00373"></a>00373 <span class="comment"></span>
<a name="l00374"></a>00374 <span class="comment">/** </span>
<a name="l00375"></a>00375 <span class="comment">  Get a pointer to the task whose ID comes after a given ID.</span>
<a name="l00376"></a>00376 <span class="comment">  FreeRTOS assigns each task a unique ID number internally.  This function will</span>
<a name="l00377"></a>00377 <span class="comment">  return a pointer to the task with the next ID.  Note that this does not necessarily</span>
<a name="l00378"></a>00378 <span class="comment">  mean that this task will be given processor time next, just that its ID is the next </span>
<a name="l00379"></a>00379 <span class="comment">  one along in the list of all tasks.</span>
<a name="l00380"></a>00380 <span class="comment"></span>
<a name="l00381"></a>00381 <span class="comment">  This is an expensive function since it needs to stop the scheduler to search the lists</span>
<a name="l00382"></a>00382 <span class="comment">  of tasks.  It should only really be used in a debug setting.</span>
<a name="l00383"></a>00383 <span class="comment">  @param task A pointer to the previous task.</span>
<a name="l00384"></a>00384 <span class="comment">  @return A pointer to the task that's next in the ID list.</span>
<a name="l00385"></a>00385 <span class="comment">  </span>
<a name="l00386"></a>00386 <span class="comment">\par Example</span>
<a name="l00387"></a>00387 <span class="comment">\code</span>
<a name="l00388"></a>00388 <span class="comment">void *oneTask = TaskCreate( MyTask, "Mine", 1000, 0, 1 );</span>
<a name="l00389"></a>00389 <span class="comment">void *nextTask = TaskGetNext( oneTask );</span>
<a name="l00390"></a>00390 <span class="comment">\endcode</span>
<a name="l00391"></a>00391 <span class="comment">*/</span>
<a name="l00392"></a><a class="code" href="group___tasks.html#ga8d7aef54edaea894b5f5e9cd6c53eae">00392</a> <span class="keywordtype">void</span>* <a class="code" href="group___tasks.html#ga8d7aef54edaea894b5f5e9cd6c53eae" title="Get a pointer to the task whose ID comes after a given ID.">TaskGetNext</a>( <span class="keywordtype">void</span>* task )
<a name="l00393"></a>00393 {
<a name="l00394"></a>00394   <span class="keywordtype">void</span>* taskreturn = NULL;
<a name="l00395"></a>00395   vTaskSuspendAll();
<a name="l00396"></a>00396   {
<a name="l00397"></a>00397     taskreturn = TaskGetNext_internal( task );
<a name="l00398"></a>00398   }
<a name="l00399"></a>00399   xTaskResumeAll( );
<a name="l00400"></a>00400   <span class="keywordflow">return</span> taskreturn;
<a name="l00401"></a>00401 }
<a name="l00402"></a>00402 <span class="comment"></span>
<a name="l00403"></a>00403 <span class="comment">/** </span>
<a name="l00404"></a>00404 <span class="comment">  Get the total number of tasks that exist at a given moment.</span>
<a name="l00405"></a>00405 <span class="comment">  @return An integer specifying the number of tasks.</span>
<a name="l00406"></a>00406 <span class="comment">  </span>
<a name="l00407"></a>00407 <span class="comment">\par Example</span>
<a name="l00408"></a>00408 <span class="comment">\code</span>
<a name="l00409"></a>00409 <span class="comment">int numberOfTasks = GetNumberOfTasks( );</span>
<a name="l00410"></a>00410 <span class="comment">\endcode</span>
<a name="l00411"></a>00411 <span class="comment">*/</span>
<a name="l00412"></a><a class="code" href="group___tasks.html#g87597a6d75dce6de737707604d4267ce">00412</a> <span class="keywordtype">int</span> <a class="code" href="group___tasks.html#g87597a6d75dce6de737707604d4267ce" title="Get the total number of tasks that exist at a given moment.">GetNumberOfTasks</a>( )
<a name="l00413"></a>00413 {
<a name="l00414"></a>00414   <span class="keywordflow">return</span> uxTaskGetNumberOfTasks( );
<a name="l00415"></a>00415 }
<a name="l00416"></a>00416 <span class="comment"></span>
<a name="l00417"></a>00417 <span class="comment">/** </span>
<a name="l00418"></a>00418 <span class="comment">  Update the priority of a task.</span>
<a name="l00419"></a>00419 <span class="comment">  Higher numbers mean higher priority/more processor time.</span>
<a name="l00420"></a>00420 <span class="comment">  @param task A pointer to the task you want to update.</span>
<a name="l00421"></a>00421 <span class="comment">  @param priority An integer specifying the new priority.</span>
<a name="l00422"></a>00422 <span class="comment">  </span>
<a name="l00423"></a>00423 <span class="comment">\par Example</span>
<a name="l00424"></a>00424 <span class="comment">\code</span>
<a name="l00425"></a>00425 <span class="comment">void *task = TaskCreate( MyTask, "Mine", 1000, 0, 1 ); // create a task</span>
<a name="l00426"></a>00426 <span class="comment">// ... now update the task's priority to 6</span>
<a name="l00427"></a>00427 <span class="comment">TaskSetPriority( task, 6 );</span>
<a name="l00428"></a>00428 <span class="comment">\endcode</span>
<a name="l00429"></a>00429 <span class="comment">*/</span>
<a name="l00430"></a><a class="code" href="group___tasks.html#g713d7e60380194c8a1ff830c80f37061">00430</a> <span class="keywordtype">void</span> <a class="code" href="group___tasks.html#g713d7e60380194c8a1ff830c80f37061" title="Update the priority of a task.">TaskSetPriority</a>( <span class="keywordtype">void</span>* task, <span class="keywordtype">int</span> priority )
<a name="l00431"></a>00431 {
<a name="l00432"></a>00432   vTaskPrioritySet( task, priority );
<a name="l00433"></a>00433 }
<a name="l00434"></a>00434 <span class="comment"></span>
<a name="l00435"></a>00435 <span class="comment">/** </span>
<a name="l00436"></a>00436 <span class="comment">  Returns the number of ticks since the scheduler started.</span>
<a name="l00437"></a>00437 <span class="comment">  @return the number of ticks</span>
<a name="l00438"></a>00438 <span class="comment">*/</span>
<a name="l00439"></a><a class="code" href="group___tasks.html#gc899bfb04919f3af158289bdcb2901de">00439</a> <span class="keywordtype">int</span> <a class="code" href="group___tasks.html#gc899bfb04919f3af158289bdcb2901de" title="Returns the number of ticks since the scheduler started.">TaskGetTickCount</a>( <span class="keywordtype">void</span> )
<a name="l00440"></a>00440 {
<a name="l00441"></a>00441   <span class="keywordflow">return</span> xTaskGetTickCount( );
<a name="l00442"></a>00442 }
<a name="l00443"></a>00443 <span class="comment"></span>
<a name="l00444"></a>00444 <span class="comment">/** @}</span>
<a name="l00445"></a>00445 <span class="comment">*/</span>
<a name="l00446"></a>00446 <span class="comment"></span>
<a name="l00447"></a>00447 <span class="comment">/** \defgroup Utils Utilities</span>
<a name="l00448"></a>00448 <span class="comment">  General utilities provided by the RTOS.</span>
<a name="l00449"></a>00449 <span class="comment">  </span>
<a name="l00450"></a>00450 <span class="comment">  FreeRTOS has several options for memory management - we've chosen a default one here which</span>
<a name="l00451"></a>00451 <span class="comment">  is pretty sensible in most cases, but you're of course welcome to use whatever makes most </span>
<a name="l00452"></a>00452 <span class="comment">  sense for your application.  See http://www.freertos.org/a00111.html for</span>
<a name="l00453"></a>00453 <span class="comment">  the available options.</span>
<a name="l00454"></a>00454 <span class="comment"></span>
<a name="l00455"></a>00455 <span class="comment">* \ingroup RTOS</span>
<a name="l00456"></a>00456 <span class="comment">* @{</span>
<a name="l00457"></a>00457 <span class="comment">*/</span>
<a name="l00458"></a>00458 <span class="comment"></span>
<a name="l00459"></a>00459 <span class="comment">/** </span>
<a name="l00460"></a>00460 <span class="comment">  Dynamically allocate memory from the heap.</span>
<a name="l00461"></a>00461 <span class="comment">  This is pretty much the same as a normal malloc(), but for the SAM7X. </span>
<a name="l00462"></a>00462 <span class="comment">  @return A pointer to the allocated memory, or NULL if the memory was not available.</span>
<a name="l00463"></a>00463 <span class="comment">  @see Free(), System_GetFreeMemory( )</span>
<a name="l00464"></a>00464 <span class="comment">  </span>
<a name="l00465"></a>00465 <span class="comment">  \par Example</span>
<a name="l00466"></a>00466 <span class="comment">  \code</span>
<a name="l00467"></a>00467 <span class="comment">  int bufferSize = 1024;</span>
<a name="l00468"></a>00468 <span class="comment">  char *bufferPtr = Malloc( bufferSize );</span>
<a name="l00469"></a>00469 <span class="comment">  // now you have a 1024 character buffer</span>
<a name="l00470"></a>00470 <span class="comment">  \endcode</span>
<a name="l00471"></a>00471 <span class="comment">*/</span>
<a name="l00472"></a><a class="code" href="group___utils.html#gf8ee6a74b03a39bce7c3b7d95fea303c">00472</a> <span class="keywordtype">void</span>* <a class="code" href="group___utils.html#gf8ee6a74b03a39bce7c3b7d95fea303c" title="Dynamically allocate memory from the heap.">Malloc</a>( <span class="keywordtype">int</span> size )
<a name="l00473"></a>00473 {
<a name="l00474"></a>00474   <span class="keywordflow">return</span> pvPortMalloc( size );
<a name="l00475"></a>00475 }
<a name="l00476"></a>00476 <span class="comment"></span>
<a name="l00477"></a>00477 <span class="comment">/** </span>
<a name="l00478"></a>00478 <span class="comment">  Same as Malloc, but keeps trying until it succeeds.</span>
<a name="l00479"></a>00479 <span class="comment">  This is a convenience function that will continue to call Malloc( ) at a given interval until</span>
<a name="l00480"></a>00480 <span class="comment">  it returns successfully.  Once this function returns, you know you have been allocated the memory</span>
<a name="l00481"></a>00481 <span class="comment">  you asked for.</span>
<a name="l00482"></a>00482 <span class="comment">  </span>
<a name="l00483"></a>00483 <span class="comment">  @param size An integer specifying the amount of memory, in bytes, you want to allocate.</span>
<a name="l00484"></a>00484 <span class="comment">  @param interval An integer specifying the number of milliseconds to wait between successive attempts to allocate memory.  </span>
<a name="l00485"></a>00485 <span class="comment">  It's best to not set this too low, as it will be a bit taxing on the system.</span>
<a name="l00486"></a>00486 <span class="comment">  @return A pointer to the allocated memory, or NULL if the memory was not available.</span>
<a name="l00487"></a>00487 <span class="comment">  @see Free(), System_GetFreeMemory( )</span>
<a name="l00488"></a>00488 <span class="comment">  </span>
<a name="l00489"></a>00489 <span class="comment">  \par Example</span>
<a name="l00490"></a>00490 <span class="comment">  \code</span>
<a name="l00491"></a>00491 <span class="comment">  char *bufferPtr = MallocWait( 1024, 100 );</span>
<a name="l00492"></a>00492 <span class="comment">  // now you have a 1024 character buffer</span>
<a name="l00493"></a>00493 <span class="comment">  \endcode</span>
<a name="l00494"></a>00494 <span class="comment">*/</span>
<a name="l00495"></a><a class="code" href="group___utils.html#g95923aa748602fa0330903fca05ca892">00495</a> <span class="keywordtype">void</span>* <a class="code" href="group___utils.html#g95923aa748602fa0330903fca05ca892" title="Same as Malloc, but keeps trying until it succeeds.">MallocWait</a>( <span class="keywordtype">int</span> size, <span class="keywordtype">int</span> interval )
<a name="l00496"></a>00496 {
<a name="l00497"></a>00497   <span class="keywordtype">void</span>* retval = NULL;
<a name="l00498"></a>00498   <span class="keywordflow">while</span>( retval == NULL )
<a name="l00499"></a>00499   {
<a name="l00500"></a>00500     retval = <a class="code" href="group___utils.html#gf8ee6a74b03a39bce7c3b7d95fea303c" title="Dynamically allocate memory from the heap.">Malloc</a>( size );
<a name="l00501"></a>00501     <span class="keywordflow">if</span>( retval )
<a name="l00502"></a>00502       <span class="keywordflow">return</span> retval;
<a name="l00503"></a>00503     <span class="keywordflow">else</span>
<a name="l00504"></a>00504       <a class="code" href="group___tasks.html#g9a64a7c0e24f257826103d1d1bbb44fa" title="Put a task to sleep for a given number of milliseconds.">Sleep</a>( interval );
<a name="l00505"></a>00505   }
<a name="l00506"></a>00506   <span class="keywordflow">return</span> NULL; <span class="comment">// should never get here</span>
<a name="l00507"></a>00507 }
<a name="l00508"></a>00508 <span class="comment"></span>
<a name="l00509"></a>00509 <span class="comment">/** </span>
<a name="l00510"></a>00510 <span class="comment">  Free memory from the heap.</span>
<a name="l00511"></a>00511 <span class="comment">  Once you've allocated memory using Malloc(), free it when you're done with it.</span>
<a name="l00512"></a>00512 <span class="comment">  It's usually a good idea to set the pointer the freed memory to NULL after you've freed it.</span>
<a name="l00513"></a>00513 <span class="comment">  @param memory A pointer to the memory created by Malloc( )</span>
<a name="l00514"></a>00514 <span class="comment">  @see Malloc(), System_GetFreeMemory( )</span>
<a name="l00515"></a>00515 <span class="comment">  </span>
<a name="l00516"></a>00516 <span class="comment">  \par Example</span>
<a name="l00517"></a>00517 <span class="comment">  \code</span>
<a name="l00518"></a>00518 <span class="comment">  char *bufferPtr = Malloc( 1024 ); // allocate 1024 bytes of memory</span>
<a name="l00519"></a>00519 <span class="comment">  // ...your processing here...</span>
<a name="l00520"></a>00520 <span class="comment">  Free( bufferPtr ); // then free the memory when you're done with it</span>
<a name="l00521"></a>00521 <span class="comment">  \endcode</span>
<a name="l00522"></a>00522 <span class="comment">*/</span>
<a name="l00523"></a><a class="code" href="group___utils.html#g6b0be54448d6ce393134400f4b22fa97">00523</a> <span class="keywordtype">void</span> <a class="code" href="group___utils.html#g6b0be54448d6ce393134400f4b22fa97" title="Free memory from the heap.">Free</a>( <span class="keywordtype">void</span>* memory )
<a name="l00524"></a>00524 {
<a name="l00525"></a>00525   vPortFree( memory ); 
<a name="l00526"></a>00526 }
<a name="l00527"></a>00527 <span class="comment"></span>
<a name="l00528"></a>00528 <span class="comment">/** @}</span>
<a name="l00529"></a>00529 <span class="comment">*/</span>
<a name="l00530"></a>00530 <span class="comment"></span>
<a name="l00531"></a>00531 <span class="comment">/** \defgroup Queues Queues</span>
<a name="l00532"></a>00532 <span class="comment">  Queues allow for thread-safe inter-process communication.</span>
<a name="l00533"></a>00533 <span class="comment">  A queue is a list of items that can be passed from one task to another.</span>
<a name="l00534"></a>00534 <span class="comment">  Items are placed in a queue by copy - not by reference. It is therefore preferable, </span>
<a name="l00535"></a>00535 <span class="comment">  when queuing large items, to only queue a pointer to the item.  Tasks can block on a </span>
<a name="l00536"></a>00536 <span class="comment">  queue to wait for either data to become available on the queue, or space to become available to write to the queue.</span>
<a name="l00537"></a>00537 <span class="comment">  </span>
<a name="l00538"></a>00538 <span class="comment">  More info at http://www.freertos.org - some documentation here used from the FreeRTOS doc by Richard Barry.</span>
<a name="l00539"></a>00539 <span class="comment">* \ingroup RTOS</span>
<a name="l00540"></a>00540 <span class="comment">* @{</span>
<a name="l00541"></a>00541 <span class="comment">*/</span>
<a name="l00542"></a>00542 <span class="comment"></span>
<a name="l00543"></a>00543 <span class="comment">/** </span>
<a name="l00544"></a>00544 <span class="comment">  Create a new queue.</span>
<a name="l00545"></a>00545 <span class="comment">  This allocates storage for the queue.  It's usually a good idea to pass around pointers on queues</span>
<a name="l00546"></a>00546 <span class="comment">  as opposed to whole data structures, as that's quite resource intensive.</span>
<a name="l00547"></a>00547 <span class="comment">  @param length The maximum number of items that the queue can contain.</span>
<a name="l00548"></a>00548 <span class="comment">  @param itemSize The number of bytes each item in the queue will require.  Items are queued by copy, not by reference, </span>
<a name="l00549"></a>00549 <span class="comment">  so this is the number of bytes that will be copied for each posted item.  Each item on the queue must be the same size.</span>
<a name="l00550"></a>00550 <span class="comment">  @return A pointer to the queue on success, 0 if the queue couldn't be created.</span>
<a name="l00551"></a>00551 <span class="comment">  </span>
<a name="l00552"></a>00552 <span class="comment">  \par Example</span>
<a name="l00553"></a>00553 <span class="comment">  \code</span>
<a name="l00554"></a>00554 <span class="comment">  struct myData_</span>
<a name="l00555"></a>00555 <span class="comment">  {</span>
<a name="l00556"></a>00556 <span class="comment">    int count;</span>
<a name="l00557"></a>00557 <span class="comment">    char buffer[100];</span>
<a name="l00558"></a>00558 <span class="comment">  };</span>
<a name="l00559"></a>00559 <span class="comment"></span>
<a name="l00560"></a>00560 <span class="comment">  // create a queue that can hold 5 pointers to myData structures</span>
<a name="l00561"></a>00561 <span class="comment">  struct MyData_* myData;</span>
<a name="l00562"></a>00562 <span class="comment">  void* myQueue = QueueCreate( 5, sizeof( myData* ) );</span>
<a name="l00563"></a>00563 <span class="comment">  if( myQueue == 0 )</span>
<a name="l00564"></a>00564 <span class="comment">    // then the queue can't be used.</span>
<a name="l00565"></a>00565 <span class="comment">  else</span>
<a name="l00566"></a>00566 <span class="comment">    // continue processing...</span>
<a name="l00567"></a>00567 <span class="comment">  \endcode</span>
<a name="l00568"></a>00568 <span class="comment">*/</span>
<a name="l00569"></a><a class="code" href="group___queues.html#gc2d1cdfeaaa00285b5c67260c0d2a64d">00569</a> <span class="keywordtype">void</span>* <a class="code" href="group___queues.html#gc2d1cdfeaaa00285b5c67260c0d2a64d" title="Create a new queue.">QueueCreate</a>( uint length, uint itemSize )
<a name="l00570"></a>00570 {
<a name="l00571"></a>00571   <span class="keywordflow">return</span> xQueueCreate( length, itemSize );
<a name="l00572"></a>00572 }
<a name="l00573"></a>00573 <span class="comment"></span>
<a name="l00574"></a>00574 <span class="comment">/** </span>
<a name="l00575"></a>00575 <span class="comment">  Post an item onto the front of a queue.</span>
<a name="l00576"></a>00576 <span class="comment">  The item is queued by copy, not by reference.  This function must not be called from an interrupt service routine.</span>
<a name="l00577"></a>00577 <span class="comment">  See xQueueSendFromISR () for an alternative which may be used in an ISR.</span>
<a name="l00578"></a>00578 <span class="comment">  @param queue The queue to send to.</span>
<a name="l00579"></a>00579 <span class="comment">  @param itemToQueue A pointer to the item to send on the queue.  </span>
<a name="l00580"></a>00580 <span class="comment">  @param msToWait The maximum number of milliseconds the task should block waiting for space to become available on the queue, </span>
<a name="l00581"></a>00581 <span class="comment">  should it already be full.  The call will return immediately if this is set to 0.</span>
<a name="l00582"></a>00582 <span class="comment">  @return 1 on success, 0 on failure.</span>
<a name="l00583"></a>00583 <span class="comment">  </span>
<a name="l00584"></a>00584 <span class="comment">  \par Example</span>
<a name="l00585"></a>00585 <span class="comment">  \code</span>
<a name="l00586"></a>00586 <span class="comment">  struct MyData_</span>
<a name="l00587"></a>00587 <span class="comment">  {</span>
<a name="l00588"></a>00588 <span class="comment">    int count;</span>
<a name="l00589"></a>00589 <span class="comment">    char buffer[100];</span>
<a name="l00590"></a>00590 <span class="comment">  };</span>
<a name="l00591"></a>00591 <span class="comment"></span>
<a name="l00592"></a>00592 <span class="comment">  // create a queue that can hold 5 pointers to myData structures</span>
<a name="l00593"></a>00593 <span class="comment">  struct MyData_* myData;</span>
<a name="l00594"></a>00594 <span class="comment">  void* myQueue = QueueCreate( 5, sizeof( myData* ) );</span>
<a name="l00595"></a>00595 <span class="comment">  if( myQueue )</span>
<a name="l00596"></a>00596 <span class="comment">  {</span>
<a name="l00597"></a>00597 <span class="comment">    if( QueueSendToFront( myQueue, (void*)&amp;myData, 10 ) ) // wait 10 ms to send if queue is full</span>
<a name="l00598"></a>00598 <span class="comment">      // then we're all set</span>
<a name="l00599"></a>00599 <span class="comment">    else</span>
<a name="l00600"></a>00600 <span class="comment">      // deal with an unsuccessful send</span>
<a name="l00601"></a>00601 <span class="comment">  }</span>
<a name="l00602"></a>00602 <span class="comment">  \endcode</span>
<a name="l00603"></a>00603 <span class="comment">*/</span>
<a name="l00604"></a><a class="code" href="group___queues.html#gcb0105420a21d83abeb9abc04f412e9f">00604</a> <span class="keywordtype">int</span> <a class="code" href="group___queues.html#gcb0105420a21d83abeb9abc04f412e9f" title="Post an item onto the front of a queue.">QueueSendToFront</a>( <span class="keywordtype">void</span>* queue, <span class="keywordtype">void</span>* itemToQueue, <span class="keywordtype">int</span> msToWait )
<a name="l00605"></a>00605 {
<a name="l00606"></a>00606   <span class="keywordflow">return</span> xQueueSend( queue, itemToQueue, msToWait / portTICK_RATE_MS );
<a name="l00607"></a>00607 }
<a name="l00608"></a>00608 <span class="comment"></span>
<a name="l00609"></a>00609 <span class="comment">/** </span>
<a name="l00610"></a>00610 <span class="comment">  Post an item onto the back of a queue.</span>
<a name="l00611"></a>00611 <span class="comment">  The item is queued by copy, not by reference.  This function must not be called from an interrupt service routine.</span>
<a name="l00612"></a>00612 <span class="comment">  See xQueueSendFromISR () for an alternative which may be used in an ISR.</span>
<a name="l00613"></a>00613 <span class="comment">  @param queue The queue to send to.</span>
<a name="l00614"></a>00614 <span class="comment">  @param itemToQueue A pointer to the item to send on the queue.  </span>
<a name="l00615"></a>00615 <span class="comment">  @param msToWait The maximum number of milliseconds the task should block waiting for space to become available on the queue, </span>
<a name="l00616"></a>00616 <span class="comment">  should it already be full.  The call will return immediately if this is set to 0.</span>
<a name="l00617"></a>00617 <span class="comment">  @return 1 on success, 0 on failure.</span>
<a name="l00618"></a>00618 <span class="comment">  </span>
<a name="l00619"></a>00619 <span class="comment">  \par Example</span>
<a name="l00620"></a>00620 <span class="comment">  \code</span>
<a name="l00621"></a>00621 <span class="comment">  struct MyData_</span>
<a name="l00622"></a>00622 <span class="comment">  {</span>
<a name="l00623"></a>00623 <span class="comment">    int count;</span>
<a name="l00624"></a>00624 <span class="comment">    char buffer[100];</span>
<a name="l00625"></a>00625 <span class="comment">  };</span>
<a name="l00626"></a>00626 <span class="comment"></span>
<a name="l00627"></a>00627 <span class="comment">  // create a queue that can hold 5 pointers to myData structures</span>
<a name="l00628"></a>00628 <span class="comment">  struct MyData_* myData;</span>
<a name="l00629"></a>00629 <span class="comment">  void* myQueue = QueueCreate( 5, sizeof( myData* ) );</span>
<a name="l00630"></a>00630 <span class="comment">  if( myQueue )</span>
<a name="l00631"></a>00631 <span class="comment">  {</span>
<a name="l00632"></a>00632 <span class="comment">    if( QueueSendToBack( myQueue, (void*)&amp;myData, 10 ) ) // wait 10 ms to send if queue is full</span>
<a name="l00633"></a>00633 <span class="comment">      // then we're all set</span>
<a name="l00634"></a>00634 <span class="comment">    else</span>
<a name="l00635"></a>00635 <span class="comment">      // deal with an unsuccessful send</span>
<a name="l00636"></a>00636 <span class="comment">  }</span>
<a name="l00637"></a>00637 <span class="comment">  \endcode</span>
<a name="l00638"></a>00638 <span class="comment">*/</span>
<a name="l00639"></a><a class="code" href="group___queues.html#g24a3155b7ac8bd256eeb82bcc4b6d9aa">00639</a> <span class="keywordtype">int</span> <a class="code" href="group___queues.html#g24a3155b7ac8bd256eeb82bcc4b6d9aa" title="Post an item onto the back of a queue.">QueueSendToBack</a>( <span class="keywordtype">void</span>* queue, <span class="keywordtype">void</span>* itemToQueue, <span class="keywordtype">int</span> msToWait )
<a name="l00640"></a>00640 {
<a name="l00641"></a>00641   <span class="keywordflow">return</span> xQueueSend( queue, itemToQueue, msToWait / portTICK_RATE_MS );
<a name="l00642"></a>00642 }
<a name="l00643"></a>00643 <span class="comment"></span>
<a name="l00644"></a>00644 <span class="comment">/** </span>
<a name="l00645"></a>00645 <span class="comment">  Read an item off of a queue.</span>
<a name="l00646"></a>00646 <span class="comment">  The item is received by copy so a buffer of adequate size must be provided. </span>
<a name="l00647"></a>00647 <span class="comment">  The number of bytes copied into the buffer was defined when the queue was created.</span>
<a name="l00648"></a>00648 <span class="comment">  The item will be removed from the queue once it is read.</span>
<a name="l00649"></a>00649 <span class="comment">  </span>
<a name="l00650"></a>00650 <span class="comment">  This function must not be used in an interrupt service routine. See QueueReceiveFromISR( ) for an alternative that can.</span>
<a name="l00651"></a>00651 <span class="comment">  @param queue The queue to receive from.</span>
<a name="l00652"></a>00652 <span class="comment">  @param buffer A pointer to the buffer the item will be read into.  </span>
<a name="l00653"></a>00653 <span class="comment">  @param msToWait The maximum number of milliseconds the task should block waiting for an item to show up on the queue, </span>
<a name="l00654"></a>00654 <span class="comment">  should it be empty.</span>
<a name="l00655"></a>00655 <span class="comment">  @return 1 on success, 0 on failure.</span>
<a name="l00656"></a>00656 <span class="comment">  </span>
<a name="l00657"></a>00657 <span class="comment">  \par Example</span>
<a name="l00658"></a>00658 <span class="comment">  \code</span>
<a name="l00659"></a>00659 <span class="comment">  struct MyData_</span>
<a name="l00660"></a>00660 <span class="comment">  {</span>
<a name="l00661"></a>00661 <span class="comment">    int count;</span>
<a name="l00662"></a>00662 <span class="comment">    char buffer[100];</span>
<a name="l00663"></a>00663 <span class="comment">  };</span>
<a name="l00664"></a>00664 <span class="comment">  </span>
<a name="l00665"></a>00665 <span class="comment">  void* myQueue;</span>
<a name="l00666"></a>00666 <span class="comment">  </span>
<a name="l00667"></a>00667 <span class="comment">  void SomeTask( void* p )</span>
<a name="l00668"></a>00668 <span class="comment">  {</span>
<a name="l00669"></a>00669 <span class="comment">    // create a queue that can hold 5 pointers to myData structures</span>
<a name="l00670"></a>00670 <span class="comment">    myQueue = QueueCreate( 5, sizeof( myData* ) );</span>
<a name="l00671"></a>00671 <span class="comment">    struct MyData_ myData; // the data we'll be sending</span>
<a name="l00672"></a>00672 <span class="comment">    myData.count = 12;</span>
<a name="l00673"></a>00673 <span class="comment">    myData.buffer = "ABCDEF";</span>
<a name="l00674"></a>00674 <span class="comment">    </span>
<a name="l00675"></a>00675 <span class="comment">    QueueSendToFront( myQueue, &amp;myData, 0 );</span>
<a name="l00676"></a>00676 <span class="comment">  }</span>
<a name="l00677"></a>00677 <span class="comment">  </span>
<a name="l00678"></a>00678 <span class="comment">  void AnotherTask( void* p )</span>
<a name="l00679"></a>00679 <span class="comment">  {</span>
<a name="l00680"></a>00680 <span class="comment">    int dataSize = sizeof( struct MyData_ );</span>
<a name="l00681"></a>00681 <span class="comment">    struct MyData_* rxData; // a pointer to some data</span>
<a name="l00682"></a>00682 <span class="comment">    if( myQueue )</span>
<a name="l00683"></a>00683 <span class="comment">    {</span>
<a name="l00684"></a>00684 <span class="comment">      if( QueueReceive( myQueue, rxData, 100 ) ) // wait up to 100 milliseconds for data</span>
<a name="l00685"></a>00685 <span class="comment">      {</span>
<a name="l00686"></a>00686 <span class="comment">        // now rxData points to the data posted in SomeTask</span>
<a name="l00687"></a>00687 <span class="comment">      }</span>
<a name="l00688"></a>00688 <span class="comment">    }</span>
<a name="l00689"></a>00689 <span class="comment">  }</span>
<a name="l00690"></a>00690 <span class="comment">  \endcode</span>
<a name="l00691"></a>00691 <span class="comment">*/</span>
<a name="l00692"></a><a class="code" href="group___queues.html#ge6957dcef9dfcf94627ddf6b56e46983">00692</a> <span class="keywordtype">int</span> <a class="code" href="group___queues.html#ge6957dcef9dfcf94627ddf6b56e46983" title="Read an item off of a queue.">QueueReceive</a>( <span class="keywordtype">void</span>* queue, <span class="keywordtype">void</span>* buffer, <span class="keywordtype">int</span> msToWait )
<a name="l00693"></a>00693 {
<a name="l00694"></a>00694   <span class="keywordflow">return</span> xQueueReceive( queue, buffer, msToWait / portTICK_RATE_MS );
<a name="l00695"></a>00695 }
<a name="l00696"></a>00696 <span class="comment"></span>
<a name="l00697"></a>00697 <span class="comment">/** </span>
<a name="l00698"></a>00698 <span class="comment">  Return the number of messages waiting in a queue.</span>
<a name="l00699"></a>00699 <span class="comment"></span>
<a name="l00700"></a>00700 <span class="comment">  @param queue The queue to look at.</span>
<a name="l00701"></a>00701 <span class="comment">  @return The number of messages waiting.</span>
<a name="l00702"></a>00702 <span class="comment">  </span>
<a name="l00703"></a>00703 <span class="comment">  \par Example</span>
<a name="l00704"></a>00704 <span class="comment">  \code</span>
<a name="l00705"></a>00705 <span class="comment">  int msgs = QueueMessagesWaiting( myQueue );</span>
<a name="l00706"></a>00706 <span class="comment">  \endcode</span>
<a name="l00707"></a>00707 <span class="comment">*/</span>
<a name="l00708"></a><a class="code" href="group___queues.html#g900ddfe9c08c30101e5dce0eb8572ed3">00708</a> <span class="keywordtype">int</span> <a class="code" href="group___queues.html#g900ddfe9c08c30101e5dce0eb8572ed3" title="Return the number of messages waiting in a queue.">QueueMessagesWaiting</a>( <span class="keywordtype">void</span>* queue )
<a name="l00709"></a>00709 {
<a name="l00710"></a>00710   <span class="keywordflow">return</span> uxQueueMessagesWaiting( queue );
<a name="l00711"></a>00711 }
<a name="l00712"></a>00712 <span class="comment"></span>
<a name="l00713"></a>00713 <span class="comment">/** </span>
<a name="l00714"></a>00714 <span class="comment">  Delete a queue - freeing all the memory allocated for storing of items placed on the queue.</span>
<a name="l00715"></a>00715 <span class="comment">  @param queue The queue to delete.</span>
<a name="l00716"></a>00716 <span class="comment">  </span>
<a name="l00717"></a>00717 <span class="comment">  \par Example</span>
<a name="l00718"></a>00718 <span class="comment">  \code</span>
<a name="l00719"></a>00719 <span class="comment">  QueueDelete( myQueue );</span>
<a name="l00720"></a>00720 <span class="comment">  \endcode</span>
<a name="l00721"></a>00721 <span class="comment">*/</span>
<a name="l00722"></a><a class="code" href="group___queues.html#g732b8a550d25382ecbf8f28744a5199d">00722</a> <span class="keywordtype">void</span> <a class="code" href="group___queues.html#g732b8a550d25382ecbf8f28744a5199d" title="Delete a queue - freeing all the memory allocated for storing of items placed on...">QueueDelete</a>( <span class="keywordtype">void</span>* queue )
<a name="l00723"></a>00723 {
<a name="l00724"></a>00724   vQueueDelete( queue );
<a name="l00725"></a>00725 }
<a name="l00726"></a>00726 <span class="comment"></span>
<a name="l00727"></a>00727 <span class="comment">/** </span>
<a name="l00728"></a>00728 <span class="comment">  Post an item to the front of a queue from within an interrupt service routine.</span>
<a name="l00729"></a>00729 <span class="comment">  Items are queued by copy not reference so it is preferable to only queue small items, especially when called from an ISR. </span>
<a name="l00730"></a>00730 <span class="comment">  In most cases it would be preferable to store a pointer to the item being queued.</span>
<a name="l00731"></a>00731 <span class="comment">  @param queue The queue to send to.</span>
<a name="l00732"></a>00732 <span class="comment">  @param itemToSend A pointer to the item to send on the queue.  The size of the items the queue will hold was defined </span>
<a name="l00733"></a>00733 <span class="comment">  when the queue was created, so this many bytes will be copied from itemToSend into the queue storage area.</span>
<a name="l00734"></a>00734 <span class="comment">  @param taskPreviouslyWoken This is included so an ISR can post onto the same queue multiple times from a single interrupt. </span>
<a name="l00735"></a>00735 <span class="comment">  The first call should always pass in 0. Subsequent calls should pass in the value returned from the previous call.</span>
<a name="l00736"></a>00736 <span class="comment">  @return 1 if a task was woken by posting onto the queue. This is used by the ISR to determine if a context </span>
<a name="l00737"></a>00737 <span class="comment">  switch may be required following the ISR.</span>
<a name="l00738"></a>00738 <span class="comment">  </span>
<a name="l00739"></a>00739 <span class="comment">  \par Example</span>
<a name="l00740"></a>00740 <span class="comment">  \code</span>
<a name="l00741"></a>00741 <span class="comment">  struct MyData_</span>
<a name="l00742"></a>00742 <span class="comment">  {</span>
<a name="l00743"></a>00743 <span class="comment">    int count;</span>
<a name="l00744"></a>00744 <span class="comment">    char buffer[100];</span>
<a name="l00745"></a>00745 <span class="comment">  };</span>
<a name="l00746"></a>00746 <span class="comment">  </span>
<a name="l00747"></a>00747 <span class="comment">  int taskWokenByPost = 0; // be sure to initialize to 0</span>
<a name="l00748"></a>00748 <span class="comment"></span>
<a name="l00749"></a>00749 <span class="comment">  // create a queue that can hold 5 pointers to myData structures</span>
<a name="l00750"></a>00750 <span class="comment">  struct MyData_ myData;</span>
<a name="l00751"></a>00751 <span class="comment">  void* myQueue = QueueCreate( 5, sizeof( myData* ) );</span>
<a name="l00752"></a>00752 <span class="comment">  if( myQueue )</span>
<a name="l00753"></a>00753 <span class="comment">  {</span>
<a name="l00754"></a>00754 <span class="comment">    taskWokenByPost = QueueSendToFrontFromISR( myQueue, (void*)&amp;myData, taskWokenByPost )</span>
<a name="l00755"></a>00755 <span class="comment">    if( taskWokenByPost )</span>
<a name="l00756"></a>00756 <span class="comment">    {</span>
<a name="l00757"></a>00757 <span class="comment">        // We should switch context so the ISR returns to a different task.    </span>
<a name="l00758"></a>00758 <span class="comment">        portYIELD_FROM_ISR( );</span>
<a name="l00759"></a>00759 <span class="comment">    }</span>
<a name="l00760"></a>00760 <span class="comment">  }</span>
<a name="l00761"></a>00761 <span class="comment">  \endcode</span>
<a name="l00762"></a>00762 <span class="comment">*/</span>
<a name="l00763"></a><a class="code" href="group___queues.html#gbd4e727f53b330ab99f56db41459e5ad">00763</a> <span class="keywordtype">int</span> <a class="code" href="group___queues.html#gbd4e727f53b330ab99f56db41459e5ad" title="Post an item to the front of a queue from within an interrupt service routine.">QueueSendToFrontFromISR</a>( <span class="keywordtype">void</span>* queue, <span class="keywordtype">void</span>* itemToSend, <span class="keywordtype">int</span> taskPreviouslyWoken )
<a name="l00764"></a>00764 {
<a name="l00765"></a>00765   <span class="keywordflow">return</span> xQueueSendToFrontFromISR( queue, itemToSend, taskPreviouslyWoken );
<a name="l00766"></a>00766 }
<a name="l00767"></a>00767 <span class="comment"></span>
<a name="l00768"></a>00768 <span class="comment">/** </span>
<a name="l00769"></a>00769 <span class="comment">  Post an item to the back of a queue from within an interrupt service routine.</span>
<a name="l00770"></a>00770 <span class="comment">  Items are queued by copy not reference so it is preferable to only queue small items, especially when called from an ISR. </span>
<a name="l00771"></a>00771 <span class="comment">  In most cases it would be preferable to store a pointer to the item being queued.</span>
<a name="l00772"></a>00772 <span class="comment">  @param queue The queue to send to.</span>
<a name="l00773"></a>00773 <span class="comment">  @param itemToSend A pointer to the item to send on the queue.  The size of the items the queue will hold was defined </span>
<a name="l00774"></a>00774 <span class="comment">  when the queue was created, so this many bytes will be copied from itemToSend into the queue storage area.</span>
<a name="l00775"></a>00775 <span class="comment">  @param taskPreviouslyWoken This is included so an ISR can post onto the same queue multiple times from a single interrupt. </span>
<a name="l00776"></a>00776 <span class="comment">  The first call should always pass in 0. Subsequent calls should pass in the value returned from the previous call.</span>
<a name="l00777"></a>00777 <span class="comment">  @return 1 if a task was woken by posting onto the queue. This is used by the ISR to determine if a context </span>
<a name="l00778"></a>00778 <span class="comment">  switch may be required following the ISR.</span>
<a name="l00779"></a>00779 <span class="comment">  </span>
<a name="l00780"></a>00780 <span class="comment">  \par Example</span>
<a name="l00781"></a>00781 <span class="comment">  \code</span>
<a name="l00782"></a>00782 <span class="comment">  struct MyData_</span>
<a name="l00783"></a>00783 <span class="comment">  {</span>
<a name="l00784"></a>00784 <span class="comment">    int count;</span>
<a name="l00785"></a>00785 <span class="comment">    char buffer[100];</span>
<a name="l00786"></a>00786 <span class="comment">  };</span>
<a name="l00787"></a>00787 <span class="comment">  </span>
<a name="l00788"></a>00788 <span class="comment">  int taskWokenByPost = 0; // be sure to initialize to 0</span>
<a name="l00789"></a>00789 <span class="comment"></span>
<a name="l00790"></a>00790 <span class="comment">  // create a queue that can hold 5 pointers to myData structures</span>
<a name="l00791"></a>00791 <span class="comment">  struct MyData_ myData;</span>
<a name="l00792"></a>00792 <span class="comment">  void* myQueue = QueueCreate( 5, sizeof( myData* ) );</span>
<a name="l00793"></a>00793 <span class="comment">  if( myQueue )</span>
<a name="l00794"></a>00794 <span class="comment">  {</span>
<a name="l00795"></a>00795 <span class="comment">    taskWokenByPost = QueueSendToBackFromISR( myQueue, (void*)&amp;myData, taskWokenByPost )</span>
<a name="l00796"></a>00796 <span class="comment">    if( taskWokenByPost )</span>
<a name="l00797"></a>00797 <span class="comment">    {</span>
<a name="l00798"></a>00798 <span class="comment">        // We should switch context so the ISR returns to a different task.    </span>
<a name="l00799"></a>00799 <span class="comment">        portYIELD_FROM_ISR( );</span>
<a name="l00800"></a>00800 <span class="comment">    }</span>
<a name="l00801"></a>00801 <span class="comment">  }</span>
<a name="l00802"></a>00802 <span class="comment">  \endcode</span>
<a name="l00803"></a>00803 <span class="comment">*/</span>
<a name="l00804"></a><a class="code" href="group___queues.html#gba2ceb616e0eac3cb7346ed0f76ecc23">00804</a> <span class="keywordtype">int</span> <a class="code" href="group___queues.html#gba2ceb616e0eac3cb7346ed0f76ecc23" title="Post an item to the back of a queue from within an interrupt service routine.">QueueSendToBackFromISR</a>( <span class="keywordtype">void</span>* queue, <span class="keywordtype">void</span>* itemToSend, <span class="keywordtype">int</span> taskPreviouslyWoken )
<a name="l00805"></a>00805 {
<a name="l00806"></a>00806   <span class="keywordflow">return</span> xQueueSendToBackFromISR( queue, itemToSend, taskPreviouslyWoken );
<a name="l00807"></a>00807 }
<a name="l00808"></a>00808 <span class="comment"></span>
<a name="l00809"></a>00809 <span class="comment">/** </span>
<a name="l00810"></a>00810 <span class="comment">  Receive an item from a queue from within an interrupt service routine.</span>
<a name="l00811"></a>00811 <span class="comment">  You'll need to have enough storage for the queue to copy the item into.  Receiving from a queue takes the item off the queue.</span>
<a name="l00812"></a>00812 <span class="comment">  @param queue The queue to receive from.</span>
<a name="l00813"></a>00813 <span class="comment">  @param buffer A pointer to the buffer into which the received item will be copied - ensure that there's enough room.</span>
<a name="l00814"></a>00814 <span class="comment">  @param taskWoken A task may be blocked waiting for an item to be read from the queue, freeing up space. If QueueReceiveFromISR </span>
<a name="l00815"></a>00815 <span class="comment">  causes such a task to unblock *taskWoken will get set to 1, otherwise *taskWoken will remain unchanged.</span>
<a name="l00816"></a>00816 <span class="comment">  @return 1 if an item was successfully received from the queue, otherwise 0.</span>
<a name="l00817"></a>00817 <span class="comment">  switch may be required following the ISR.</span>
<a name="l00818"></a>00818 <span class="comment">  </span>
<a name="l00819"></a>00819 <span class="comment">  \par Example</span>
<a name="l00820"></a>00820 <span class="comment">  \code</span>
<a name="l00821"></a>00821 <span class="comment">  </span>
<a name="l00822"></a>00822 <span class="comment">  int taskWokenByReceive = 0; // be sure to initialize to 0</span>
<a name="l00823"></a>00823 <span class="comment">  void* myQueue = QueueCreate( 5, sizeof( char ) );</span>
<a name="l00824"></a>00824 <span class="comment">  if( myQueue == 0 )</span>
<a name="l00825"></a>00825 <span class="comment">    // queue couldn't be created...</span>
<a name="l00826"></a>00826 <span class="comment">  </span>
<a name="l00827"></a>00827 <span class="comment">  char data;</span>
<a name="l00828"></a>00828 <span class="comment"></span>
<a name="l00829"></a>00829 <span class="comment">  while( QueueReceiveFromISR( myQueue, (void*)&amp;data, taskWokenByReceive ) )</span>
<a name="l00830"></a>00830 <span class="comment">  {</span>
<a name="l00831"></a>00831 <span class="comment">    // process new items from queue here</span>
<a name="l00832"></a>00832 <span class="comment">    </span>
<a name="l00833"></a>00833 <span class="comment">    // If removing an item from the queue woke the task that was </span>
<a name="l00834"></a>00834 <span class="comment">    // posting onto the queue, taskWokenByReceive will have been set to</span>
<a name="l00835"></a>00835 <span class="comment">    // 1.  No matter how many times this loop iterates only one</span>
<a name="l00836"></a>00836 <span class="comment">    // task will be woken.</span>
<a name="l00837"></a>00837 <span class="comment">  }</span>
<a name="l00838"></a>00838 <span class="comment">  if( taskWokenByReceive )</span>
<a name="l00839"></a>00839 <span class="comment">  {</span>
<a name="l00840"></a>00840 <span class="comment">      // We should switch context so the ISR returns to a different task.    </span>
<a name="l00841"></a>00841 <span class="comment">      taskYIELD ();</span>
<a name="l00842"></a>00842 <span class="comment">  }</span>
<a name="l00843"></a>00843 <span class="comment">  \endcode</span>
<a name="l00844"></a>00844 <span class="comment">*/</span>
<a name="l00845"></a><a class="code" href="group___queues.html#g3d94a308309a75f2c3c9a6fd1bbfc712">00845</a> <span class="keywordtype">int</span> <a class="code" href="group___queues.html#g3d94a308309a75f2c3c9a6fd1bbfc712" title="Receive an item from a queue from within an interrupt service routine.">QueueReceiveFromISR</a>( <span class="keywordtype">void</span>* queue, <span class="keywordtype">void</span>* buffer, <span class="keywordtype">long</span>* taskWoken )
<a name="l00846"></a>00846 {
<a name="l00847"></a>00847   <span class="keywordflow">return</span> xQueueReceiveFromISR( queue, buffer, taskWoken );
<a name="l00848"></a>00848 }
<a name="l00849"></a>00849 <span class="comment"></span>
<a name="l00850"></a>00850 <span class="comment">/** @}</span>
<a name="l00851"></a>00851 <span class="comment">*/</span>
<a name="l00852"></a>00852 <span class="comment"></span>
<a name="l00853"></a>00853 <span class="comment">/** \defgroup SemaphoresMutexes Semaphores &amp; Mutexes</span>
<a name="l00854"></a>00854 <span class="comment">  Thread-safe methods to protect access to shared resources.</span>
<a name="l00855"></a>00855 <span class="comment">  </span>
<a name="l00856"></a>00856 <span class="comment">  Quite often you'll have more than one task trying to get access to the same resources.  To ensure that the resource</span>
<a name="l00857"></a>00857 <span class="comment">  is not in some intermediate state between reading and writing, it's necessary to serialize access to it.  Semaphores</span>
<a name="l00858"></a>00858 <span class="comment">  and mutexes provide a way to do this.</span>
<a name="l00859"></a>00859 <span class="comment">  </span>
<a name="l00860"></a>00860 <span class="comment">  Binary semaphores and mutexes are very similar but have some subtle differences: </span>
<a name="l00861"></a>00861 <span class="comment">  Mutexes include a priority inheritance mechanism, binary semaphores do not. This makes binary semaphores the </span>
<a name="l00862"></a>00862 <span class="comment">  better choice for implementing synchronisation (between tasks or between tasks and an interrupt), and mutexes </span>
<a name="l00863"></a>00863 <span class="comment">  the better choice for implementing simple mutual exclusion.</span>
<a name="l00864"></a>00864 <span class="comment"></span>
<a name="l00865"></a>00865 <span class="comment">  A binary semaphore need not be given back once obtained, so task synchronisation can be implemented by one task/interrupt </span>
<a name="l00866"></a>00866 <span class="comment">  continuously 'giving' the semaphore while another continuously 'takes' the semaphore.</span>
<a name="l00867"></a>00867 <span class="comment"></span>
<a name="l00868"></a>00868 <span class="comment">  The priority of a task that 'takes' a mutex can potentially be raised if another task of higher priority attempts </span>
<a name="l00869"></a>00869 <span class="comment">  to obtain the same mutex. The task that owns the mutex 'inherits' the priority of the task attempting to 'take' the same mutex. </span>
<a name="l00870"></a>00870 <span class="comment">  This means the mutex must always be 'given' back - otherwise the higher priority task will never be able to obtain the mutex, </span>
<a name="l00871"></a>00871 <span class="comment">  and the lower priority task will never 'disinherit' the priority.</span>
<a name="l00872"></a>00872 <span class="comment">  </span>
<a name="l00873"></a>00873 <span class="comment">  More info at http://www.freertos.org - much documentation here used from the FreeRTOS doc by Richard Barry.</span>
<a name="l00874"></a>00874 <span class="comment">* \ingroup RTOS</span>
<a name="l00875"></a>00875 <span class="comment">* @{</span>
<a name="l00876"></a>00876 <span class="comment">*/</span>
<a name="l00877"></a>00877 <span class="comment"></span>
<a name="l00878"></a>00878 <span class="comment">/** </span>
<a name="l00879"></a>00879 <span class="comment">  Create a semaphore. </span>
<a name="l00880"></a>00880 <span class="comment">  Create a semaphore by using the existing queue mechanism. The queue length is 1 as this is a binary semaphore. </span>
<a name="l00881"></a>00881 <span class="comment">  The data size is 0 as we don't want to actually store any data - we just want to know if the queue is empty or full.</span>
<a name="l00882"></a>00882 <span class="comment">  @param semaphore The semaphore to be created.</span>
<a name="l00883"></a>00883 <span class="comment">  </span>
<a name="l00884"></a>00884 <span class="comment">  \par Example</span>
<a name="l00885"></a>00885 <span class="comment">  \code</span>
<a name="l00886"></a>00886 <span class="comment">  void* mySemaphore;</span>
<a name="l00887"></a>00887 <span class="comment">  SemaphoreCreate( mySemaphore );</span>
<a name="l00888"></a>00888 <span class="comment">  if( mySemaphore != NULL )</span>
<a name="l00889"></a>00889 <span class="comment">  {</span>
<a name="l00890"></a>00890 <span class="comment">    // The semaphore was created successfully and can now be used.</span>
<a name="l00891"></a>00891 <span class="comment">  }</span>
<a name="l00892"></a>00892 <span class="comment">  \endcode</span>
<a name="l00893"></a>00893 <span class="comment">*/</span>
<a name="l00894"></a><a class="code" href="group___semaphores_mutexes.html#gfa1700ecb9afca5ad4c1bcd832039838">00894</a> <span class="keywordtype">void</span> <a class="code" href="group___semaphores_mutexes.html#gfa1700ecb9afca5ad4c1bcd832039838" title="Create a semaphore.">SemaphoreCreate</a>( <span class="keywordtype">void</span>* semaphore )
<a name="l00895"></a>00895 {
<a name="l00896"></a>00896   vSemaphoreCreateBinary( semaphore );
<a name="l00897"></a>00897 }
<a name="l00898"></a>00898 
<a name="l00899"></a>00899 <span class="preprocessor">#if ( configUSE_MUTEXES == 1 )</span>
<a name="l00900"></a>00900 <span class="preprocessor"></span><span class="keywordtype">void</span>* MutexCreate( )
<a name="l00901"></a>00901 {
<a name="l00902"></a>00902   <span class="keywordflow">return</span> xQueueCreateMutex( );
<a name="l00903"></a>00903 }
<a name="l00904"></a>00904 <span class="preprocessor">#endif</span>
<a name="l00905"></a>00905 <span class="preprocessor"></span><span class="comment"></span>
<a name="l00906"></a>00906 <span class="comment">/** </span>
<a name="l00907"></a>00907 <span class="comment">  Obtain a semaphore. </span>
<a name="l00908"></a>00908 <span class="comment">  The semaphore must have first been created with SemaphoreCreate( ).</span>
<a name="l00909"></a>00909 <span class="comment">  @param semaphore The semaphore to take.</span>
<a name="l00910"></a>00910 <span class="comment">  @param blockTime The time, in milliseconds, to wait for the semaphore to become available.</span>
<a name="l00911"></a>00911 <span class="comment">  @return 1 if the semaphore was obtained. 0 if blockTime expired without the semaphore becoming available.</span>
<a name="l00912"></a>00912 <span class="comment">  @see SemaphoreCreate( ), SemaphoreGive( )</span>
<a name="l00913"></a>00913 <span class="comment">  </span>
<a name="l00914"></a>00914 <span class="comment">  \par Example</span>
<a name="l00915"></a>00915 <span class="comment">  \code</span>
<a name="l00916"></a>00916 <span class="comment">  void* mySemaphore;</span>
<a name="l00917"></a>00917 <span class="comment">  SemaphoreCreate( mySemaphore );</span>
<a name="l00918"></a>00918 <span class="comment">  if( SemaphoreTake( mySemaphore, 100 ) ) // wait 100 milliseconds on this semaphore</span>
<a name="l00919"></a>00919 <span class="comment">  {</span>
<a name="l00920"></a>00920 <span class="comment">    // now access the protected resources</span>
<a name="l00921"></a>00921 <span class="comment">  }</span>
<a name="l00922"></a>00922 <span class="comment">  \endcode</span>
<a name="l00923"></a>00923 <span class="comment">*/</span>
<a name="l00924"></a><a class="code" href="group___semaphores_mutexes.html#g2637a3b208dd56f3313a7b3b3d9ea55d">00924</a> <span class="keywordtype">int</span> <a class="code" href="group___semaphores_mutexes.html#g2637a3b208dd56f3313a7b3b3d9ea55d" title="Obtain a semaphore.">SemaphoreTake</a>( <span class="keywordtype">void</span>* semaphore, <span class="keywordtype">int</span> blockTime )
<a name="l00925"></a>00925 {
<a name="l00926"></a>00926   <span class="keywordflow">return</span> xSemaphoreTake( semaphore, blockTime / portTICK_RATE_MS );
<a name="l00927"></a>00927 }
<a name="l00928"></a>00928 <span class="comment"></span>
<a name="l00929"></a>00929 <span class="comment">/** </span>
<a name="l00930"></a>00930 <span class="comment">  Release a semaphore. </span>
<a name="l00931"></a>00931 <span class="comment">  This must not be used from an ISR. See SemaphoreGiveFromISR( ) for an alternative which can be used from an ISR.</span>
<a name="l00932"></a>00932 <span class="comment">  @param semaphore The semaphore to release.</span>
<a name="l00933"></a>00933 <span class="comment">  @return 1 if the semaphore was released. 0 if an error occurred. Semaphores are implemented using queues. </span>
<a name="l00934"></a>00934 <span class="comment">  An error can occur if there is no space on the queue to post a message - indicating that the semaphore was not first obtained correctly.</span>
<a name="l00935"></a>00935 <span class="comment">  @see SemaphoreCreate( ), SemaphoreTake( )</span>
<a name="l00936"></a>00936 <span class="comment">  </span>
<a name="l00937"></a>00937 <span class="comment">  \par Example</span>
<a name="l00938"></a>00938 <span class="comment">  \code</span>
<a name="l00939"></a>00939 <span class="comment">  void* mySemaphore;</span>
<a name="l00940"></a>00940 <span class="comment">  SemaphoreCreate( mySemaphore );</span>
<a name="l00941"></a>00941 <span class="comment">  if( SemaphoreTake( mySemaphore, 1000 ) ) // wait 1000 milliseconds on this semaphore</span>
<a name="l00942"></a>00942 <span class="comment">  {</span>
<a name="l00943"></a>00943 <span class="comment">    // access the protected resources</span>
<a name="l00944"></a>00944 <span class="comment">    </span>
<a name="l00945"></a>00945 <span class="comment">    // then release the semaphore</span>
<a name="l00946"></a>00946 <span class="comment">    if( !SemaphoreGive( mySemaphore ) )</span>
<a name="l00947"></a>00947 <span class="comment">      // then handle the error here</span>
<a name="l00948"></a>00948 <span class="comment">  }</span>
<a name="l00949"></a>00949 <span class="comment">  \endcode</span>
<a name="l00950"></a>00950 <span class="comment">*/</span>
<a name="l00951"></a><a class="code" href="group___semaphores_mutexes.html#gf6b6a05f387c0c8c671fe8c2491a5d43">00951</a> <span class="keywordtype">int</span> <a class="code" href="group___semaphores_mutexes.html#gf6b6a05f387c0c8c671fe8c2491a5d43" title="Release a semaphore.">SemaphoreGive</a>( <span class="keywordtype">void</span>* semaphore )
<a name="l00952"></a>00952 {
<a name="l00953"></a>00953   <span class="keywordflow">return</span> xSemaphoreGive( semaphore );
<a name="l00954"></a>00954 }
<a name="l00955"></a>00955 <span class="comment"></span>
<a name="l00956"></a>00956 <span class="comment">/** </span>
<a name="l00957"></a>00957 <span class="comment">  Release a semaphore from within an ISR. </span>
<a name="l00958"></a>00958 <span class="comment">  This must not be used from an ISR. See SemaphoreGiveFromISR( ) for an alternative which can be used from an ISR.</span>
<a name="l00959"></a>00959 <span class="comment">  @param semaphore The semaphore to release.</span>
<a name="l00960"></a>00960 <span class="comment">  @param taskWoken This is included so an ISR can make multiple calls to SemaphoreGiveFromISR() from a single interrupt. </span>
<a name="l00961"></a>00961 <span class="comment">  The first call should always pass in 0. Subsequent calls should pass in the value returned from the previous call.  </span>
<a name="l00962"></a>00962 <span class="comment">  @return 1 if the semaphore was released. 0 if an error occurred. Semaphores are implemented using queues. </span>
<a name="l00963"></a>00963 <span class="comment">  An error can occur if there is no space on the queue to post a message - indicating that the semaphore was not first obtained correctly.</span>
<a name="l00964"></a>00964 <span class="comment">  </span>
<a name="l00965"></a>00965 <span class="comment">  \par Example</span>
<a name="l00966"></a>00966 <span class="comment">  \code</span>
<a name="l00967"></a>00967 <span class="comment">  void* mySemaphore;</span>
<a name="l00968"></a>00968 <span class="comment">  SemaphoreCreate( mySemaphore );</span>
<a name="l00969"></a>00969 <span class="comment">  void TimerISR( )</span>
<a name="l00970"></a>00970 <span class="comment">  {</span>
<a name="l00971"></a>00971 <span class="comment">    static int taskWoken = 0;</span>
<a name="l00972"></a>00972 <span class="comment">    taskWoken = SemaphoreGiveFromISR( mySemaphore, taskWoken );</span>
<a name="l00973"></a>00973 <span class="comment">    // If taskWoken was set to true you may want to yield (force a switch)</span>
<a name="l00974"></a>00974 <span class="comment">    // here.</span>
<a name="l00975"></a>00975 <span class="comment">  }</span>
<a name="l00976"></a>00976 <span class="comment">  \endcode</span>
<a name="l00977"></a>00977 <span class="comment">*/</span>
<a name="l00978"></a><a class="code" href="group___semaphores_mutexes.html#g4d883250a869e5064e92a3ae7ebc5c9e">00978</a> <span class="keywordtype">int</span> <a class="code" href="group___semaphores_mutexes.html#g4d883250a869e5064e92a3ae7ebc5c9e" title="Release a semaphore from within an ISR.">SemaphoreGiveFromISR</a>( <span class="keywordtype">void</span>* semaphore, <span class="keywordtype">int</span> taskWoken )
<a name="l00979"></a>00979 {
<a name="l00980"></a>00980   <span class="keywordflow">return</span> xSemaphoreGiveFromISR( semaphore, taskWoken );
<a name="l00981"></a>00981 }
<a name="l00982"></a>00982 <span class="comment"></span>
<a name="l00983"></a>00983 <span class="comment">/** @}</span>
<a name="l00984"></a>00984 <span class="comment">*/</span>
<a name="l00985"></a>00985 
<a name="l00986"></a>00986 <span class="keywordtype">void</span>* TaskGetNext_internal( <span class="keywordtype">void</span>* task )
<a name="l00987"></a>00987 {
<a name="l00988"></a>00988   <span class="keywordtype">int</span> currentID;
<a name="l00989"></a>00989   <span class="keywordtype">int</span> lowID = 1024; <span class="comment">// some large number that will be greater than the number of tasks...</span>
<a name="l00990"></a>00990   <span class="keywordtype">int</span> highID = 1024;
<a name="l00991"></a>00991   <span class="keywordtype">void</span>* lowTask = NULL;
<a name="l00992"></a>00992   <span class="keywordtype">void</span>* highTask = NULL;
<a name="l00993"></a>00993   <span class="keywordtype">void</span>* tcb = NULL;
<a name="l00994"></a>00994   <span class="keywordtype">unsigned</span> portBASE_TYPE uxQueue = <a class="code" href="group___tasks.html#g4f0b02fb8a36b62908efd6b649339d19" title="Read the highest priority being used by any existing task.">TaskGetTopPriorityUsed</a>( ) + 1;
<a name="l00995"></a>00995 
<a name="l00996"></a>00996   <span class="keywordflow">if</span>( task == NULL )
<a name="l00997"></a>00997     currentID = 1;
<a name="l00998"></a>00998   <span class="keywordflow">else</span>
<a name="l00999"></a>00999     currentID = <a class="code" href="group___tasks.html#g39806aeaa7dd24062f13c3118ca1b990" title="Get the ID number of a task.">TaskGetIDNumber</a>( task );
<a name="l01000"></a>01000 
<a name="l01001"></a>01001   <span class="comment">// look through all the possible lists of tasks</span>
<a name="l01002"></a>01002     <span class="keywordflow">do</span>
<a name="l01003"></a>01003     {
<a name="l01004"></a>01004       uxQueue--;
<a name="l01005"></a>01005       <span class="keywordflow">if</span>( !listLIST_IS_EMPTY( GetReadyTaskByPriority( uxQueue ) ) )
<a name="l01006"></a>01006       {
<a name="l01007"></a>01007         tcb = iterateForNextTask( &amp;lowTask, &amp;lowID, &amp;highTask, &amp;highID, currentID, GetReadyTaskByPriority( uxQueue ) );
<a name="l01008"></a>01008         <span class="keywordflow">if</span>( tcb != NULL )
<a name="l01009"></a>01009           <span class="keywordflow">return</span> tcb;
<a name="l01010"></a>01010       }   
<a name="l01011"></a>01011     }<span class="keywordflow">while</span>( uxQueue &gt; ( <span class="keywordtype">unsigned</span> portSHORT ) tskIDLE_PRIORITY );
<a name="l01012"></a>01012 
<a name="l01013"></a>01013     <span class="comment">// check the list of delayed tasks</span>
<a name="l01014"></a>01014     <span class="keywordflow">if</span>( !listLIST_IS_EMPTY( GetDelayedTaskList( ) ) )
<a name="l01015"></a>01015     {
<a name="l01016"></a>01016       tcb = iterateForNextTask( &amp;lowTask, &amp;lowID, &amp;highTask, &amp;highID, currentID, GetDelayedTaskList( ) );
<a name="l01017"></a>01017       <span class="keywordflow">if</span>( tcb != NULL )
<a name="l01018"></a>01018         <span class="keywordflow">return</span> tcb;
<a name="l01019"></a>01019     }
<a name="l01020"></a>01020     <span class="comment">// check the list of overflow delayed tasks</span>
<a name="l01021"></a>01021     <span class="keywordflow">if</span>( !listLIST_IS_EMPTY( GetOverflowDelayedTaskList( ) ) )
<a name="l01022"></a>01022     {
<a name="l01023"></a>01023       tcb = iterateForNextTask( &amp;lowTask, &amp;lowID, &amp;highTask, &amp;highID, currentID, GetOverflowDelayedTaskList( ) );
<a name="l01024"></a>01024       <span class="keywordflow">if</span>( tcb != NULL )
<a name="l01025"></a>01025         <span class="keywordflow">return</span> tcb;
<a name="l01026"></a>01026     }
<a name="l01027"></a>01027     <span class="comment">// check the list of tasks about to die</span>
<a name="l01028"></a>01028     <span class="keywordflow">if</span>( !listLIST_IS_EMPTY( GetListOfTasksWaitingTermination( ) ) )
<a name="l01029"></a>01029     {
<a name="l01030"></a>01030       tcb = iterateForNextTask( &amp;lowTask, &amp;lowID, &amp;highTask, &amp;highID, currentID, GetListOfTasksWaitingTermination( ) );
<a name="l01031"></a>01031       <span class="keywordflow">if</span>( tcb != NULL )
<a name="l01032"></a>01032         <span class="keywordflow">return</span> tcb;
<a name="l01033"></a>01033     }
<a name="l01034"></a>01034     <span class="comment">// check the list of suspended tasks</span>
<a name="l01035"></a>01035     <span class="keywordflow">if</span>( !listLIST_IS_EMPTY( GetSuspendedTaskList( ) ) )
<a name="l01036"></a>01036       tcb = iterateForNextTask( &amp;lowTask, &amp;lowID, &amp;highTask, &amp;highID, currentID, GetSuspendedTaskList( ) );
<a name="l01037"></a>01037 
<a name="l01038"></a>01038     
<a name="l01039"></a>01039   <span class="keywordflow">if</span>( highTask )
<a name="l01040"></a>01040     <span class="keywordflow">return</span> highTask;
<a name="l01041"></a>01041   <span class="keywordflow">else</span>
<a name="l01042"></a>01042     <span class="keywordflow">return</span> lowTask;
<a name="l01043"></a>01043 }
<a name="l01044"></a>01044 
<a name="l01045"></a>01045 <span class="comment">// one function to search either by name or ID</span>
<a name="l01046"></a>01046 <span class="comment">// pass in a garbage value for the parameter you're not interested in</span>
<a name="l01047"></a>01047 <span class="keywordtype">void</span>* findTask( <span class="keywordtype">char</span> *taskName, <span class="keywordtype">int</span> taskID )
<a name="l01048"></a>01048 {
<a name="l01049"></a>01049   <span class="keywordtype">bool</span> byName;
<a name="l01050"></a>01050   <span class="keywordflow">if</span>( taskName == NULL &amp;&amp; taskID &gt; 0 )
<a name="l01051"></a>01051     byName = <span class="keyword">false</span>;
<a name="l01052"></a>01052   <span class="keywordflow">if</span>( taskName != NULL &amp;&amp; taskID &lt; 0 )
<a name="l01053"></a>01053     byName = <span class="keyword">true</span>;
<a name="l01054"></a>01054 
<a name="l01055"></a>01055   <span class="keywordtype">unsigned</span> portBASE_TYPE uxQueue = <a class="code" href="group___tasks.html#g4f0b02fb8a36b62908efd6b649339d19" title="Read the highest priority being used by any existing task.">TaskGetTopPriorityUsed</a>( ) + 1;
<a name="l01056"></a>01056   <span class="keywordtype">void</span> *tcb = NULL;
<a name="l01057"></a>01057 
<a name="l01058"></a>01058   <span class="comment">// look through all the possible lists of tasks</span>
<a name="l01059"></a>01059     <span class="keywordflow">do</span>
<a name="l01060"></a>01060     {
<a name="l01061"></a>01061       uxQueue--;
<a name="l01062"></a>01062       <span class="keywordflow">if</span>( !listLIST_IS_EMPTY( GetReadyTaskByPriority( uxQueue ) ) )
<a name="l01063"></a>01063       {
<a name="l01064"></a>01064         <span class="keywordflow">if</span>( byName )
<a name="l01065"></a>01065           tcb = iterateByName( taskName, GetReadyTaskByPriority( uxQueue ) );
<a name="l01066"></a>01066         <span class="keywordflow">else</span>
<a name="l01067"></a>01067           tcb = iterateByID( taskID, GetReadyTaskByPriority( uxQueue ) );
<a name="l01068"></a>01068 
<a name="l01069"></a>01069         <span class="keywordflow">if</span>( tcb != NULL )
<a name="l01070"></a>01070           <span class="keywordflow">return</span> tcb;
<a name="l01071"></a>01071       }   
<a name="l01072"></a>01072     }<span class="keywordflow">while</span>( uxQueue &gt; ( <span class="keywordtype">unsigned</span> portSHORT ) tskIDLE_PRIORITY );
<a name="l01073"></a>01073 
<a name="l01074"></a>01074     <span class="comment">// check the list of delayed tasks</span>
<a name="l01075"></a>01075     <span class="keywordflow">if</span>( !listLIST_IS_EMPTY( GetDelayedTaskList( ) ) )
<a name="l01076"></a>01076     {
<a name="l01077"></a>01077       <span class="keywordflow">if</span>( byName)
<a name="l01078"></a>01078         tcb = iterateByName( taskName, GetDelayedTaskList( ) );
<a name="l01079"></a>01079       <span class="keywordflow">else</span>
<a name="l01080"></a>01080         tcb = iterateByID( taskID, GetDelayedTaskList( ) );
<a name="l01081"></a>01081 
<a name="l01082"></a>01082       <span class="keywordflow">if</span>( tcb != NULL )
<a name="l01083"></a>01083         <span class="keywordflow">return</span> tcb;
<a name="l01084"></a>01084     }
<a name="l01085"></a>01085     <span class="comment">// check the list of overflow delayed tasks</span>
<a name="l01086"></a>01086     <span class="keywordflow">if</span>( !listLIST_IS_EMPTY( GetOverflowDelayedTaskList( ) ) )
<a name="l01087"></a>01087     {
<a name="l01088"></a>01088       <span class="keywordflow">if</span>( byName )
<a name="l01089"></a>01089         tcb = iterateByName( taskName, GetOverflowDelayedTaskList( ) );
<a name="l01090"></a>01090       <span class="keywordflow">else</span>
<a name="l01091"></a>01091         tcb = iterateByID( taskID, GetOverflowDelayedTaskList( ) );
<a name="l01092"></a>01092       <span class="keywordflow">if</span>( tcb != NULL )
<a name="l01093"></a>01093         <span class="keywordflow">return</span> tcb;
<a name="l01094"></a>01094     }
<a name="l01095"></a>01095     <span class="comment">// check the list of tasks about to die</span>
<a name="l01096"></a>01096     <span class="keywordflow">if</span>( !listLIST_IS_EMPTY( GetListOfTasksWaitingTermination( ) ) )
<a name="l01097"></a>01097     {
<a name="l01098"></a>01098       <span class="keywordflow">if</span>( byName )
<a name="l01099"></a>01099         tcb = iterateByName( taskName, GetListOfTasksWaitingTermination( ) );
<a name="l01100"></a>01100       <span class="keywordflow">else</span>
<a name="l01101"></a>01101         tcb = iterateByID( taskID, GetListOfTasksWaitingTermination( ) );
<a name="l01102"></a>01102 
<a name="l01103"></a>01103       <span class="keywordflow">if</span>( tcb != NULL )
<a name="l01104"></a>01104         <span class="keywordflow">return</span> tcb;
<a name="l01105"></a>01105     }
<a name="l01106"></a>01106     <span class="comment">// check the list of suspended tasks</span>
<a name="l01107"></a>01107     <span class="keywordflow">if</span>( !listLIST_IS_EMPTY( GetSuspendedTaskList( ) ) )
<a name="l01108"></a>01108     {
<a name="l01109"></a>01109       <span class="keywordflow">if</span>( byName )
<a name="l01110"></a>01110         tcb = iterateByName( taskName, GetSuspendedTaskList( ) );
<a name="l01111"></a>01111       <span class="keywordflow">else</span>
<a name="l01112"></a>01112         tcb = iterateByID( taskID, GetSuspendedTaskList( ) );
<a name="l01113"></a>01113     }
<a name="l01114"></a>01114     <span class="keywordflow">return</span> tcb;
<a name="l01115"></a>01115 }
<a name="l01116"></a>01116 
<a name="l01117"></a>01117 <span class="keywordtype">void</span>* iterateByID( <span class="keywordtype">int</span> <span class="keywordtype">id</span>, xList* pxList )
<a name="l01118"></a>01118 {
<a name="l01119"></a>01119   <span class="keywordtype">void</span> *pxNextTCB, *pxFirstTCB;
<a name="l01120"></a>01120   listGET_OWNER_OF_NEXT_ENTRY( pxFirstTCB, pxList );
<a name="l01121"></a>01121   <span class="keywordflow">do</span>
<a name="l01122"></a>01122   {
<a name="l01123"></a>01123     listGET_OWNER_OF_NEXT_ENTRY( pxNextTCB, pxList );
<a name="l01124"></a>01124     <span class="keywordflow">if</span>( <a class="code" href="group___tasks.html#g39806aeaa7dd24062f13c3118ca1b990" title="Get the ID number of a task.">TaskGetIDNumber</a>( pxNextTCB ) == <span class="keywordtype">id</span> )
<a name="l01125"></a>01125       <span class="keywordflow">return</span> pxNextTCB;
<a name="l01126"></a>01126     
<a name="l01127"></a>01127   } <span class="keywordflow">while</span>( pxNextTCB != pxFirstTCB );
<a name="l01128"></a>01128   <span class="comment">// if we get down here, we didn't find it.</span>
<a name="l01129"></a>01129   <span class="keywordflow">return</span> NULL;
<a name="l01130"></a>01130 }
<a name="l01131"></a>01131 
<a name="l01132"></a>01132 <span class="keywordtype">void</span>* iterateByName( <span class="keywordtype">char</span>* taskName, xList* pxList )
<a name="l01133"></a>01133 {
<a name="l01134"></a>01134   <span class="keywordtype">void</span> *pxNextTCB, *pxFirstTCB;
<a name="l01135"></a>01135   listGET_OWNER_OF_NEXT_ENTRY( pxFirstTCB, pxList );
<a name="l01136"></a>01136   <span class="keywordflow">do</span>
<a name="l01137"></a>01137   {
<a name="l01138"></a>01138     listGET_OWNER_OF_NEXT_ENTRY( pxNextTCB, pxList );
<a name="l01139"></a>01139     <span class="keywordflow">if</span>( strcmp( <a class="code" href="group___tasks.html#ga15296e2b927abaadce9ed3028917afd" title="Get the name of a task.">TaskGetName</a>( pxNextTCB ), taskName ) == 0 )
<a name="l01140"></a>01140       <span class="keywordflow">return</span> pxNextTCB;
<a name="l01141"></a>01141     
<a name="l01142"></a>01142   } <span class="keywordflow">while</span>( pxNextTCB != pxFirstTCB );
<a name="l01143"></a>01143   <span class="comment">// if we get down here, we didn't find it.</span>
<a name="l01144"></a>01144   <span class="keywordflow">return</span> NULL;
<a name="l01145"></a>01145 }
<a name="l01146"></a>01146 
<a name="l01147"></a>01147 <span class="keywordtype">void</span>* iterateForNextTask( <span class="keywordtype">void</span>** lowTask, <span class="keywordtype">int</span>* lowID, <span class="keywordtype">void</span>** highTask, <span class="keywordtype">int</span>* highID, <span class="keywordtype">int</span> currentID, xList* pxList )
<a name="l01148"></a>01148 {
<a name="l01149"></a>01149   <span class="keywordtype">void</span> *pxNextTCB, *pxFirstTCB;
<a name="l01150"></a>01150   listGET_OWNER_OF_NEXT_ENTRY( pxFirstTCB, pxList );
<a name="l01151"></a>01151   <span class="keywordflow">do</span>
<a name="l01152"></a>01152   {
<a name="l01153"></a>01153     listGET_OWNER_OF_NEXT_ENTRY( pxNextTCB, pxList );
<a name="l01154"></a>01154     <span class="keywordtype">int</span> <span class="keywordtype">id</span> = <a class="code" href="group___tasks.html#g39806aeaa7dd24062f13c3118ca1b990" title="Get the ID number of a task.">TaskGetIDNumber</a>( pxNextTCB );
<a name="l01155"></a>01155     <span class="keywordflow">if</span>( <span class="keywordtype">id</span> == (currentID + 1) ) <span class="comment">// if it's the ID we're looking for plus one, we got it and we're out.</span>
<a name="l01156"></a>01156       <span class="keywordflow">return</span> pxNextTCB;
<a name="l01157"></a>01157     <span class="keywordflow">if</span>( <span class="keywordtype">id</span> &gt; currentID &amp;&amp; <span class="keywordtype">id</span> &lt; *highID )
<a name="l01158"></a>01158     {
<a name="l01159"></a>01159       *highID = id;
<a name="l01160"></a>01160       *highTask = pxNextTCB;
<a name="l01161"></a>01161     }
<a name="l01162"></a>01162     <span class="keywordflow">if</span>( <span class="keywordtype">id</span> &lt; currentID &amp;&amp; <span class="keywordtype">id</span> &lt; *lowID &amp;&amp; <span class="keywordtype">id</span> != 1 ) <span class="comment">// we don't want id 1 since that's IDLE and there's no real task there.</span>
<a name="l01163"></a>01163     {
<a name="l01164"></a>01164       *lowID = id;
<a name="l01165"></a>01165       *lowTask = pxNextTCB;
<a name="l01166"></a>01166     }
<a name="l01167"></a>01167   } <span class="keywordflow">while</span>( pxNextTCB != pxFirstTCB );
<a name="l01168"></a>01168   <span class="comment">// if we get down here, we didn't find it.</span>
<a name="l01169"></a>01169   <span class="keywordflow">return</span> NULL;
<a name="l01170"></a>01170 }
<a name="l01171"></a>01171 
<a name="l01172"></a>01172 
<a name="l01173"></a>01173 
<a name="l01174"></a>01174 
<a name="l01175"></a>01175 
</pre></div><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Make Controller Kit</title>
<style type="text/css">
<!--
.footer {
	font-family: Verdana, Arial, Helvetica, sans-serif;
	font-size: 9pt;
	color: #999999;
}
-->
</style>
</head>

<body>
<hr size="1">
<div>
  <p class="footer">The Make Controller Kit is an open source project maintained by <a href="http://www.makingthings.com">MakingThings</a>.<br />
    MakingThings code is released under the <a href="http://www.apache.org/licenses/LICENSE-2.0.html" target="_blank">Apache 2.0 license</a>.<br />
    Bug tracker, development wiki and status can be found at <a href="http://dev.makingthings.com">http://dev.makingthings.com</a>.<br />
		This document was last updated on 5 Dec 2007.
</p>
</div>
<!-- Google Analytics Code -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-769030-1";
urchinTracker();
</script>
</body>
</html>
